@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/inbound-mail-foundation/retention-sweep.js

@@ -1,28 +1,30 @@
-// Inbound-mail data-retention (#957). DSGVO Art. 5 (Datenminimierung):
-// ohne Retention wachsen read_inbound_messages + die File-Storage-Bodies
-// unbegrenzt. Zwei Targets, zwei Mechanismen — der Unterschied ist
-// event-sourced vs. unmanaged:
+// Inbound-mail data retention. DSGVO Art. 5 (data minimization):
+// without retention, read_inbound_messages and the file-storage bodies grow
+// without bound. Two targets, two mechanisms—the difference is
+// event-sourced versus unmanaged:
 //
-//   read_inbound_messages (event-sourced, EXPLIZITE r.projection):
-//     pro Row aelter als messageRetentionDays → archiveStream + Row-Delete
-//     (+ bodyRef-Objekt loeschen). archiveStream statt executor.forget, weil
-//     die Projection nur das received-Domain-Event mappt, nicht den
-//     forgotten-Auto-Verb (den registriert nur ImplicitProjection). Ein
-//     forget-Event wuerde beim Rebuild ignoriert und die Row aus dem
-//     received-Event resurrecten (#648-Klasse). Der archivierte Stream macht
-//     loadAggregate leer → received wird gar nicht erst repliziert. Gleiches
-//     Muster wie tenant-destroy-hook, nur per-Row-cutoff statt ganzer Tenant.
+//   read_inbound_messages (event-sourced, EXPLICIT r.projection):
+//     each Row older than messageRetentionDays → archiveStream + Row delete
+//     (+ delete the bodyRef object). archiveStream instead of executor.forget
+//     because the projection maps only the received domain event, not the
+//     forgotten auto-verb (which only ImplicitProjection registers). A
+//     forget event would be ignored during a rebuild, causing the Row to be
+//     resurrected from the received event. The archived stream makes
+//     loadAggregate empty, so received is not replicated in the first place.
+//     Same pattern as tenant-destroy-hook, but with a per-Row cutoff instead
+//     of an entire Tenant.
 //
-//   store_mail_seen_messages (unmanaged, direct-write, nicht event-sourced):
-//     Dedup-Anker braucht nur das Backfill-/Replay-Fenster → seenAt-cutoff
-//     via plain deleteMany, kein Stream/Archiv. Gescoped direkt über die
-//     tenant_id-Spalte der Tabelle (table-builder-Konvention), kein Account-Join.
+//   store_mail_seen_messages (unmanaged, direct-write, not event-sourced):
+//     The deduplication anchor is needed only for the backfill/replay window →
+//     seenAt cutoff via plain deleteMany, with no stream/archive. Scoped
+//     directly through the table's tenant_id column (table-builder convention),
+//     without an Account join.
 //
-// GRENZE (#957 Teil 2, Plan §3.4): die PII in den Message-Events bleibt
-// unter dem TENANT-Subject-Key entschluesselbar — per-Row-Retention
-// shreddet keinen Key. Echte Art.-17-Erasure der Event-Payloads passiert
-// erst bei tenant-destroy (Key-Erase). Read-Row + Body-File sind nach dem
-// Sweep weg; das Event-Log ist append-only by design.
+// LIMITATION: the PII in the message events remains decryptable under the
+// TENANT subject key—per-Row retention does not shred a key. Actual Art.-17
+// erasure of event payloads happens only during tenant-destroy (key erasure).
+// The read Row and body file are gone after the sweep; the event log is
+// append-only by design.
 import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { archiveStream, deleteRowsWithoutReplayableStream, } from "@cosmicdrift/kumiko-framework/event-store";
 import { seenMessageTable } from "./entities.js";
@@ -46,18 +48,18 @@ async function purgeExpiredMessages(args, cutoff) {
     let messagesPurged = 0;
     let bodyObjectsDeleted = 0;
     let bodyObjectErrors = 0;
-    // Drain-Loop: jede Page loescht die Rows die sie liest, die naechste ist
-    // damit frisch. archiveStream VOR dem Delete (crash dazwischen → naechster
-    // Lauf re-archiviert idempotent + loescht). Delete strikt nach den
-    // archivierten ids, nie per cutoff-WHERE — sonst koennte eine zwischen
-    // select und delete eingegangene Alt-Mail unarchiviert geloescht werden
-    // und beim Rebuild resurrecten.
+    // Drain loop: each page deletes the Rows it reads, so the next page is fresh.
+    // Run archiveStream BEFORE deletion: if a crash occurs in between, the next
+    // run re-archives idempotently and deletes the Row. Delete strictly by the
+    // archived IDs, never with a cutoff WHERE; otherwise an old mail arriving
+    // between select and delete could be deleted without being archived and
+    // resurrected during a rebuild.
     //
-    // Ein Row deren deleteBodyObject fehlschlaegt wird NICHT geloescht — sonst
-    // ginge die einzige Referenz auf das (dann verwaiste) File-Objekt verloren
-    // (kein Retry, kein Dead-Letter). Die Row bleibt fuer den naechsten Sweep
-    // stehen (archiveStream ist idempotent). failedIds verhindert, dass so ein
-    // Row innerhalb DIESES Laufs endlos re-selektiert wird.
+    // A Row whose deleteBodyObject fails is NOT deleted; otherwise the only
+    // reference to the now-orphaned file object would be lost (no retry or
+    // dead-letter). The Row remains for the next sweep (archiveStream is
+    // idempotent). failedIds prevents such a Row from being selected endlessly
+    // during THIS run.
     const failedIds = new Set();
     for (;;) {
         const rows = (await selectMany(args.db, inboundMessagesProjectionTable, { receivedAt: { lt: cutoff }, tenantId: args.tenantId }, { limit: BATCH_LIMIT })).filter((row) => !failedIds.has(row.id));
@@ -99,9 +101,9 @@ async function purgeExpiredMessages(args, cutoff) {
     return { messagesPurged, bodyObjectsDeleted, bodyObjectErrors };
 }
 async function purgeExpiredSeenAnchors(db, tenantId, cutoff) {
-    // Seen-Anker erben tenantId (table-builder: jede Entity hat tenant_id) →
-    // direkt tenant-scoped, kein Account-Join. Trifft auch Anker, deren Account
-    // schon disconnected/geloescht ist.
+    // Seen anchors inherit tenantId (table-builder: every Entity has tenant_id) →
+    // scoped directly to the tenant, without an Account join. This also includes
+    // anchors whose Account has already been disconnected or deleted.
     const where = { tenantId, seenAt: { lt: cutoff } };
     const expired = await selectMany(db, seenMessageTable, where);
     if (expired.length === 0)

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

@@ -63,8 +63,6 @@ export const mailAccountListScreen = {
     access: MAIL_ACCOUNT_ADMIN_ACCESS,
     dormant: true,
 };
-// The reason is the audit label update-account requires; it is not in the
-// layout, so the default is what gets written.
 export const mailAccountEditScreen = {
     id: MAIL_ACCOUNT_EDIT_SCREEN_ID,
     type: "actionForm",
@@ -73,7 +71,6 @@ export const mailAccountEditScreen = {
     fields: {
         accountId: { type: "text", required: true },
         displayName: { type: "text", required: true, maxLength: 200 },
-        reason: { type: "text", default: "tenant_admin" },
     },
     layout: {
         sections: [{ fields: [{ field: "accountId", readOnly: true }, "displayName"] }],

package/dist/inbound-mail-foundation/tenant-destroy-hook.js

@@ -1,21 +1,19 @@
-// Tenant-destroy hooks — räumen beim Tenant-Destroy alle Inbound-Mail-
-// Spuren des Tenants ab. Ein Hook PRO tenant-subject-Entity (der
-// gdpr-storage-Boot-Validator prüft die EXT_TENANT_DATA-Registrierung
-// entity-genau), jeweils:
+// Tenant-destroy hooks remove all inbound-mail traces belonging to the tenant.
+// One hook per tenant-subject entity (the gdpr-storage boot validator checks
+// the EXT_TENANT_DATA registration per entity), each of which:
 //
-//   1. Streams archivieren — ein künftiger Projection-Rebuild kann
-//      Gelöschtes nicht resurrecten (Muster billing-foundation #800).
-//      Message-Streams sind viele → Loop über die Projection-Rows
-//      (Row-PK = Stream-ID); tenant-destroy ist ein seltener
-//      Batch-Vorgang, O(n) ist ok.
-//   2. Projection-Rows löschen.
-//   3. Nur mail-account: unmanaged Sync-State (Cursors, Seen-Anchors)
-//      löschen — gekeyt per accountId, deshalb aus den Account-Rows
-//      VOR dem Delete eingesammelt.
+//   1. Archives streams so a future projection rebuild cannot resurrect
+//      deleted data. Message streams are numerous, so loop over the
+//      projection rows (row PK = stream ID); tenant-destroy is a rare batch
+//      operation, so O(n) is acceptable.
+//   2. Deletes the projection rows.
+//   3. For mail-account only, deletes unmanaged sync state (cursors,
+//      seen anchors), which is keyed by accountId and must therefore be
+//      collected from the account rows BEFORE deletion.
 //
-// Die eigentliche PII-Erasure macht crypto-shredding: eraseSubjectKeys
-// löscht den Tenant-Subject-Key, damit werden Event-Log-Payloads UND
-// etwaige Ciphertext-Kopien unlesbar. Diese Hooks entsorgen die Rows.
+// The actual PII erasure uses crypto-shredding: eraseSubjectKeys deletes the
+// tenant subject key, making event-log payloads AND any ciphertext copies
+// unreadable. These hooks dispose of the rows.
 import { declareEscapeHatch } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { seenMessageTable, syncCursorTable } from "./entities.js";

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

@@ -8,8 +8,9 @@ import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "
  *   config   — tenant config reads (host/port/... of the plugins)
  *   registry — extension lookup in the factory (not plugin-internal)
  *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
- *   auditUserId  — audit identity for secret reads. Handler path: the dispatcher
- *              sets the caller user ID; worker path: system identity.
+ *   auditUserId  — audit identity for secret reads. Handler path: unset,
+ *              requireSecretsContext falls back to ctx.user.id; worker/provider
+ *              path: system identity set by the resolver.
  *   metricsFor — metrics handle of a feature by name, same behavior as
  *              HandlerContext.metricsFor: unregistered metrics are a silent
  *              no-op instead of a throw.
@@ -22,23 +23,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 +48,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 +86,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 +98,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 +128,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;
@@ -147,18 +147,18 @@ export type InboundMailProviderPlugin = {
          *  for password accounts and providers without an oauth flow. */
         readonly accessToken?: string;
         /** Batch lookup of the provider message ids not yet ingested for this
-         *  account (committed seen anchors, one query per call). Call it after
+         *  account (committed seen anchors; lists of any size are fine, queried in chunks). Call it after
          *  the listing/delta page and download MIME only for the returned ids.
          *  Ingest dedup stays the correctness anchor; this only saves downloads. */
         readonly filterUnknownMessageIds?: (providerMessageIds: readonly string[]) => Promise<ReadonlySet<string>>;
     }) => 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>;
 };