@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

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

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

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

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

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

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

@@ -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 { type DbRunner, deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -35,8 +37,8 @@ import { seenMessageTable } from "./entities.ts";
 import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "./events.ts";
 import { inboundMessagesProjectionTable } from "./projection.ts";
 
-// Temporal.Instant ohne den Caller zwingen es aus globalThis zu ziehen
-// (Muster data-retention/keep-for.ts).
+// Provides Temporal.Instant without forcing the caller to obtain it from
+// globalThis (same pattern as data-retention/keep-for.ts).
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
 export const MESSAGE_RETENTION_DAYS = 365;
@@ -48,12 +50,14 @@ const REASON = "retention_expired";
 export interface InboundRetentionArgs {
   readonly db: DbRunner;
   readonly tenantId: TenantId;
-  /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+  /**
+   * Injects the current time so tests can pin it without a date mock (pattern from keep-for.ts).
+   */
   readonly now: Instant;
   readonly messageRetentionDays?: number;
   readonly seenRetentionDays?: number;
-  /** Loescht ein file-storage-Body-Objekt per bodyRef-key. Vom Job lazy
-   *  verdrahtet (createFileProviderForTenant). Fehlt = kein Body-Delete. */
+  /** Deletes a file-storage body object by bodyRef key. Wired lazily by the job
+   * (createFileProviderForTenant); if absent, no body is deleted. */
   readonly deleteBodyObject?: (bodyRef: string) => Promise<void>;
 }
 
@@ -88,18 +92,18 @@ async function purgeExpiredMessages(
   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<string>();
   for (;;) {
     const rows = (
@@ -153,9 +157,9 @@ async function purgeExpiredSeenAnchors(
   tenantId: TenantId,
   cutoff: Instant,
 ): Promise<number> {
-  // 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<{ accountId: string }>(db, seenMessageTable, where);
   if (expired.length === 0) return 0;

package/packages/bundled-features/src/inbound-mail-foundation/tenant-destroy-hook.ts

@@ -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 type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";

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

@@ -1,14 +1,14 @@
-// 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 type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
 import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
@@ -36,23 +36,23 @@ export type InboundMailContext = {
 };
 
 /**
- * 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;
@@ -62,36 +62,35 @@ export type MailAccountRecord = {
 };
 
 /**
- * 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;
 };
 
@@ -103,8 +102,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;
 };
 
@@ -117,13 +116,13 @@ export type OAuthTokenSet = {
 };
 
 /**
- * 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[];
@@ -150,17 +149,17 @@ export type InboundOAuthFlow = {
 };
 
 /**
- * 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,
@@ -183,11 +182,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,
@@ -201,8 +200,9 @@ export type InboundMailProviderPlugin = {
   ) => Promise<() => Promise<void>>;
 };
 
-// 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: unknown): o is InboundMailProviderPlugin {
   return (
     typeof o === "object" &&
@@ -222,18 +222,17 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
 }
 
 // =============================================================================
-// 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 {
   readonly kind = "inbound-auth-error" as const;