@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

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

@@ -22,23 +22,23 @@ export type InboundMailContext = {
     readonly metricsFor?: (featureName: string) => MetricsHandle;
 };
 /**
- * Plaintext-Sicht auf ein verbundenes Postfach, wie Provider sie sehen.
- * Die Foundation decryptet `address` VOR dem Provider-Call — Provider
- * arbeiten nie mit `kumiko-pii:`-Ciphertext (Guard analog
- * withPiiCiphertextGuard im Transport-Pfad).
+ * Plaintext view of a connected mailbox exposed to providers.
+ * The Foundation decrypts `address` BEFORE the provider call; providers
+ * never receive `kumiko-pii:` ciphertext (guard analogous to
+ * withPiiCiphertextGuard in the transport path).
  */
 export type MailAccountRecord = {
-    /** = aggregateId des mail-account-Streams; zugleich Secret-Slot-Key. */
+    /** = aggregateId of the mail-account stream and the secret-slot key. */
     readonly id: string;
     readonly tenantId: string;
-    /** Provider-Key wie bei der Extension registriert ("imap", "m365-graph",
+    /** Provider key registered with the extension ("imap", "m365-graph",
      *  "gmail-rest"). */
     readonly provider: string;
-    /** "password" | "xoauth2" | "oauth" — imap unterscheidet hierüber
-     *  Formular-Connect vs. XOAUTH2-Fallback (Plan §2). */
+    /** "password" | "xoauth2" | "oauth" — imap uses this to distinguish
+     *  form-based connect from the XOAUTH2 fallback. */
     readonly authMethod: string;
-    /** null = tenant-geteiltes Postfach, sonst persönliches Postfach
-     *  dieses Users (Sichtbarkeits-Scope, Plan Entscheidung 2). */
+    /** null = tenant-shared mailbox; otherwise this user's personal mailbox
+     *  (visibility scope). */
     readonly ownerUserId: string | null;
     /** Postfach-Adresse, Plaintext (decrypted). */
     readonly address: string;
@@ -47,36 +47,35 @@ export type MailAccountRecord = {
     readonly watchState: string;
 };
 /**
- * Normalisierte eingehende Mail — Provider-Output, Ingest-Input.
- * Provider-raw-Strukturen (IMAP-Flags, Graph-Objekte) bleiben im
- * Provider; hier nur der domain-clean Schnitt.
+ * Normalized incoming mail — provider output and ingest input.
+ * Provider-specific structures (IMAP flags, Graph objects) remain in the
+ * provider; this type contains only the domain-level boundary.
  */
 export type RawInboundMessage = {
-    /** Provider-native Message-ID (IMAP UID, Graph id, Gmail id) —
-     *  Idempotency-Anchor zusammen mit providerName. */
+    /** Provider-native message ID (IMAP UID, Graph id, Gmail id) — the
+     *  idempotency anchor together with providerName. */
     readonly providerMessageId: string;
-    /** RFC-5322 Message-ID-Header ohne <>; null wenn der Header fehlt
-     *  (Foundation fällt auf deterministischen Ersatz zurück). */
+    /** RFC-5322 Message-ID header without <>; null when the header is missing
+     *  (the Foundation falls back to a deterministic replacement). */
     readonly messageIdHeader: string | null;
-    /** Provider-native Thread-/Conversation-ID falls vorhanden (Graph
-     *  conversationId, Gmail threadId); Foundation bevorzugt sie vor der
-     *  References-Chain beim threadKey-Bau. */
+    /** Provider-native thread/conversation ID when available (Graph
+     *  conversationId, Gmail threadId); the Foundation prefers it over the
+     *  References chain when building threadKey. */
     readonly providerThreadId: string | null;
-    /** References/In-Reply-To-Chain (Message-IDs ohne <>), älteste zuerst. */
+    /** References/In-Reply-To chain (message IDs without <>), oldest first. */
     readonly references: readonly string[];
     readonly from: string;
     readonly to: readonly string[];
     readonly cc: readonly string[];
     readonly subject: string;
-    /** Plaintext-Vorschau, provider-generiert oder aus dem Body geschnitten. */
+    /** Plaintext preview generated by the provider or truncated from the body. */
     readonly snippet: string;
-    /** ISO-Instant — INTERNALDATE bzw. receivedDateTime, nicht Ingest-Zeit. */
+    /** ISO instant — INTERNALDATE or receivedDateTime, not ingest time. */
     readonly receivedAtIso: string;
-    /** Raw MIME; null im snippet-only-Mode. Foundation persisted ihn nach
-     *  file-foundation und schreibt bodyRef — der Event-Store bleibt
-     *  blob-frei. */
+    /** Raw MIME; null in snippet-only mode. The Foundation persists it through
+     *  file-foundation and writes bodyRef, so the event store remains blob-free. */
     readonly rawMime: Uint8Array | null;
-    /** Generischer Scope-Hint ("inbox", Folder-Name) — keine App-Semantik. */
+    /** Generic scope hint ("inbox", folder name), with no application semantics. */
     readonly scope: string;
 };
 /** Provider-opaker Cursor: IMAP {uidValidity,lastUid} · Graph {deltaLink}
@@ -86,8 +85,8 @@ export type SyncCursorPayload = Readonly<Record<string, unknown>>;
 export type InboundFetchResult = {
     readonly messages: readonly RawInboundMessage[];
     readonly nextCursor: SyncCursorPayload;
-    /** true ⇒ Foundation ruft fetch im selben Poll-Tick erneut auf
-     *  (Pagination), bis false oder maxMessages-Budget erschöpft. */
+    /** true ⇒ the Foundation calls fetch again in the same poll tick
+     *  (pagination) until false or the maxMessages budget is exhausted. */
     readonly hasMore: boolean;
 };
 export type OAuthTokenSet = {
@@ -98,13 +97,13 @@ export type OAuthTokenSet = {
     readonly scopesGranted: readonly string[];
 };
 /**
- * OAuth-Teil des Contracts — nur OAuth-Provider; imap (Passwort-Modus)
- * lässt `oauth` weg. Die Routen (`/inbound-mail/connect`,
- * `/inbound-mail/oauth/callback`) stellt die Foundation generisch —
- * Provider registrieren KEINE eigenen Routen.
+ * OAuth portion of the contract — OAuth providers only; imap in password
+ * mode omits `oauth`. The Foundation provides the routes
+ * (`/inbound-mail/connect`, `/inbound-mail/oauth/callback`) generically;
+ * providers MUST NOT register their own routes.
  */
 export type InboundOAuthFlow = {
-    /** Scopes: Empfang UND Send in EINEM Consent — Re-Consent ist teuer. */
+    /** Scopes: request receive AND send in a SINGLE consent; re-consent is costly. */
     readonly scopes: {
         readonly receive: readonly string[];
         readonly send?: readonly string[];
@@ -128,17 +127,17 @@ export type InboundOAuthFlow = {
     }) => Promise<OAuthTokenSet>;
 };
 /**
- * Inbound-Mail-Provider-Plugin contract. Jedes Provider-Feature
- * (inbound-provider-imap, -m365-graph, -gmail-rest) registriert eine
- * Implementation via `r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION,
+ * Inbound-mail provider plugin contract. Each provider feature
+ * (inbound-provider-imap, -m365-graph, -gmail-rest) registers an
+ * implementation via `r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION,
  * "<key>", plugin)`.
  */
 export type InboundMailProviderPlugin = {
-    /** Credentials-/Erreichbarkeits-Check beim Connect-Flow — wirft
-     *  typisiert (InboundAuthError etc.), kein Rückgabewert. */
+    /** Credential/reachability check during the connect flow — throws a
+     *  typed error (InboundAuthError, etc.) and returns no value. */
     readonly verify: (ctx: InboundMailContext, account: MailAccountRecord) => Promise<void>;
-    /** Pull seit cursor. `cursor === null` ⇒ Erst-Befüllung, begrenzt
-     *  durch backfillWindowDays. */
+    /** Fetch since cursor. `cursor === null` means initial population,
+     *  limited by backfillWindowDays. */
     readonly fetch: (ctx: InboundMailContext, account: MailAccountRecord, cursor: SyncCursorPayload | null, opts: {
         readonly backfillWindowDays: number;
         readonly maxMessages: number;
@@ -154,11 +153,11 @@ export type InboundMailProviderPlugin = {
     }) => Promise<InboundFetchResult>;
     /** Nur OAuth-Provider. */
     readonly oauth?: InboundOAuthFlow;
-    /** Optional: Live-Push (IMAP IDLE, später Graph/Gmail-Webhooks).
-     *  Liefert stop(). Poll bleibt Reconciliation — watch ist Latenz-
-     *  Optimierung, nie Korrektheits-Anker. `onError` meldet den Tod der
-     *  Live-Verbindung (Drop, Auth-Revoke) an den Supervisor, der mit
-     *  Backoff neu startet — der Provider reconnected NICHT selbst. */
+    /** Optional live push (IMAP IDLE, later Graph/Gmail webhooks).
+     *  Returns stop(). Polling remains reconciliation: watch optimizes
+     *  latency but is never the correctness anchor. `onError` reports a dead
+     *  live connection (drop, auth revocation) to the supervisor, which
+     *  restarts it with backoff; the provider does NOT reconnect itself. */
     readonly watch?: (ctx: InboundMailContext, account: MailAccountRecord, handlers: {
         readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
         readonly onError: (err: unknown) => void;

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

@@ -1,17 +1,18 @@
-// Provider-Contract für inbound-mail-Provider-Plugins (Plan §2).
+// Provider contract for inbound-mail provider plugins.
 //
-// Gespiegelt von mail-foundation's MailTransportContext/-Plugin —
-// gleiche Trennung Foundation ↔ Provider, gleicher Slim-Context.
+// Mirrored from mail-foundation's MailTransportContext/-Plugin —
+// the Foundation/provider separation and slim context are identical.
 //
-// **Warum kein voller HandlerContext?** fetch()/watch() laufen im
-// Worker-Pfad (Poll-Cron, IDLE-Supervisor) — dort gibt es keinen
-// per-request `tx`/`actor`. Ein Plugin das mehr liest würde den
-// Worker-Pfad zur Runtime brechen, und das fiele nur in production
-// auf. Plugin das mehr braucht: InboundMailContext explizit erweitern
-// (sichtbarer breaking change) statt ctx-cast.
+// **Why not a full HandlerContext?** fetch()/watch() run in the worker
+// path (poll cron, IDLE supervisor), where there is no per-request
+// `tx`/`actor`. A plugin that reads more would break the worker path at
+// runtime, and this would only be noticed in production. Plugins that need
+// more must explicitly extend InboundMailContext (a visible breaking change)
+// instead of casting ctx.
 import { INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.js";
-// extension-usage `options` ist engine-payload (unknown) — strukturell
-// validieren statt blind casten (Muster isMailTransportPlugin).
+// `options` in the extension usage is an engine payload (unknown), so
+// validate its structure instead of casting blindly (patterned after
+// isMailTransportPlugin).
 export function isInboundMailProviderPlugin(o) {
     return (typeof o === "object" &&
         o !== null &&
@@ -21,18 +22,17 @@ export function isInboundMailProviderPlugin(o) {
         typeof o.fetch === "function");
 }
 // =============================================================================
-// Typisierte Fehlerklassen — Foundation reagiert einheitlich im Poll
-// (Plan §2, Fehler-Tabelle):
-//   InboundAuthError          → status=auth_error, kein Retry
-//   InboundRateLimitError     → Poll-Abbruch, nächster Cron-Tick
-//   InboundCursorInvalidError → Cursor-Reset + Voll-Resync im Backfill-
-//                               Fenster; Dedup fängt Dubletten
-//   InboundTransientError     → Job-Retry (retries: 3, exponential)
+// Typed errors handled uniformly by the Foundation during polling:
+//   InboundAuthError          → status=auth_error, no retry
+//   InboundRateLimitError     → abort poll, wait for the next cron tick
+//   InboundCursorInvalidError → reset cursor + full resync in the backfill
+//                               window; deduplication handles duplicates
+//   InboundTransientError     → job retry (retries: 3, exponential)
 // =============================================================================
 //
-// `kind`-Discriminant statt instanceof: Plugin und Foundation können in
-// getrennten Bundles leben (dual-package-hazard), instanceof über
-// Realm-/Kopie-Grenzen ist unzuverlässig.
+// Use a `kind` discriminant instead of instanceof: plugins and the Foundation
+// may run in separate bundles (dual-package-hazard), and instanceof is
+// unreliable across realm or package-copy boundaries.
 export class InboundAuthError extends Error {
     kind = "inbound-auth-error";
     constructor(message) {

package/dist/inbound-mail-foundation/watch-supervisor.d.ts

@@ -3,13 +3,13 @@ import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import { type OAuthAccessTokenManager } from "./oauth-access-token.ts";
 import { type InboundMailContext, type MailAccountRecord, type RawInboundMessage } from "./types.ts";
 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;
@@ -20,8 +20,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;
@@ -33,7 +33,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
@@ -46,8 +46,8 @@ export type InboundMailSupervisorDeps = {
 };
 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>;
 };

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,8 +63,8 @@ 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";
 export function createInboundMailSupervisor(deps) {
     const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
@@ -103,8 +102,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, {
@@ -154,7 +153,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 +166,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 +180,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 +213,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 +228,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 +240,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;
     }
@@ -272,7 +271,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 +308,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 +316,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 +368,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 +390,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 +425,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 +465,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 +493,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 +534,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 +549,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;