@cosmicdrift/kumiko-bundled-features 0.141.0 → 0.143.0

package/src/inbound-mail-foundation/feature.ts

@@ -0,0 +1,185 @@
+// kumiko-feature-version: 1
+//
+// inbound-mail-foundation — Plugin-Host für eingehende E-Mail
+// (Inbox-Föderation). Gegenstück zu mail-foundation (outbound): getrennte
+// Extension-Points, getrennter State — Architektur-Vorbild ist
+// file-foundation (Foundation besitzt State), nicht mail-transport.
+//
+// **Multi-Provider von Tag 1** (wie billing-foundation): KEIN globaler
+// `provider`-config-key. Ein Tenant verbindet parallel IMAP- und (später)
+// M365-/Gmail-Postfächer; der Provider steht pro MailAccount.
+//
+// **Was diese Foundation liefert:**
+//   1. **Plugin-API** für Inbound-Provider via r.extendsRegistrar
+//      ("inboundMailProvider"): verify/fetch/oauth?/watch? (types.ts).
+//   2. **3 event-sourced Streams** — mail-account (Lifecycle),
+//      inbound-message (genau EIN received-Event pro Mail, deterministic
+//      aggregateId ⇒ exactly-once trotz at-least-once-Ingest),
+//      mail-thread (Rollup). Volle Historie replay-fähig für spätere
+//      Consumer (Business-Prozesse: Ticket, Beleg, Auto-Antwort).
+//   3. **Inline-Projections** auf read_mail_accounts /
+//      read_inbound_messages / read_mail_threads (read-your-own-write).
+//   4. **Write-/Query-Handler**: connect/update/disconnect-account,
+//      ingest-message (programmatic, SystemAdmin), account:list +
+//      message:list (PII-decrypted, scope-gefiltert).
+//   5. **createInboundMailConnectRoutes**: OAuth-Connect + anonymer
+//      Callback (außerhalb /api/*), state HMAC-signiert.
+//   6. **createInboundMailSupervisor**: app-verdrahteter Watch-(IDLE)-
+//      Supervisor mit Backoff + Reconciliation-Poll.
+//
+// **Was diese Foundation NICHT macht:**
+//   - Keine Business-Semantik (Intent, Ticket, Zuweisung, gelesen/
+//     erledigt) — das gehört dem App-Consumer (z.B. via Event-Job auf
+//     inbound-message-received + eigener Projection).
+//   - Kein Body-Blob im Event-Store: rawMime → file-foundation via
+//     Supervisor-storeBody-Hook, Event trägt nur bodyRef.
+//   - Kein IMAP-Flag-Write-back (V1) — Inbox-Status lebt beim Consumer.
+//
+// **PII/DSGVO:** address/from/to/cc/subject/snippet sind tenantOwned —
+// encrypted VOR jedem Event-Append (einziger Write-Pfad), Event-Log UND
+// Projections tragen Ciphertext; tenant-destroy shreddet den Subject-Key
+// (crypto-shredding, Muster billing-foundation #800). Der Destroy-Hook
+// archiviert zusätzlich alle Streams + löscht die Rows.
+
+import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants";
+import {
+  inboundMessageEntity,
+  mailAccountEntity,
+  mailThreadEntity,
+  seenMessageTable,
+  syncCursorTable,
+} from "./entities";
+import {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+  INBOUND_MESSAGE_RECEIVED_EVENT_SHORT,
+  inboundMessageEventPayloadSchema,
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+  MAIL_ACCOUNT_CONNECTED_EVENT_SHORT,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  MAIL_ACCOUNT_UPDATED_EVENT_SHORT,
+  MAIL_THREAD_AGGREGATE_TYPE,
+  MAIL_THREAD_UPDATED_EVENT_QN,
+  MAIL_THREAD_UPDATED_EVENT_SHORT,
+  mailAccountEventPayloadSchema,
+  mailThreadEventPayloadSchema,
+} from "./events";
+import { connectAccountHandler } from "./handlers/connect-account.write";
+import { disconnectAccountHandler } from "./handlers/disconnect-account.write";
+import { ingestMessageHandler } from "./handlers/ingest-message.write";
+import { listAccountsQuery } from "./handlers/list-accounts.query";
+import { listMessagesQuery } from "./handlers/list-messages.query";
+import { updateAccountHandler } from "./handlers/update-account.write";
+import {
+  applyInboundMessageReceived,
+  applyMailAccountConnected,
+  applyMailAccountDisconnected,
+  applyMailAccountUpdated,
+  applyMailThreadUpdated,
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  mailThreadsProjectionTable,
+} from "./projection";
+import {
+  inboundMessageTenantDestroyHook,
+  mailAccountTenantDestroyHook,
+  mailThreadTenantDestroyHook,
+} from "./tenant-destroy-hook";
+
+export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
+  r.describe(
+    "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
+  );
+  r.uiHints({
+    displayLabel: "Inbound Mail · Foundation",
+    category: "notifications",
+    recommended: false,
+  });
+  // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
+  r.requires("tenant-lifecycle");
+
+  // 5 fine-grained domain-events (Payload-Schemas: events.ts).
+  r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema);
+  r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema);
+  r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema);
+  r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema);
+  r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema);
+
+  // Inline projections — apply in derselben TX wie der Append.
+  r.projection({
+    name: "mail-account",
+    source: MAIL_ACCOUNT_AGGREGATE_TYPE,
+    table: mailAccountsProjectionTable,
+    entity: mailAccountEntity,
+    apply: {
+      [MAIL_ACCOUNT_CONNECTED_EVENT_QN]: applyMailAccountConnected,
+      [MAIL_ACCOUNT_UPDATED_EVENT_QN]: applyMailAccountUpdated,
+      [MAIL_ACCOUNT_DISCONNECTED_EVENT_QN]: applyMailAccountDisconnected,
+    },
+  });
+  r.projection({
+    name: "inbound-message",
+    source: INBOUND_MESSAGE_AGGREGATE_TYPE,
+    table: inboundMessagesProjectionTable,
+    entity: inboundMessageEntity,
+    apply: {
+      [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
+    },
+  });
+  r.projection({
+    name: "mail-thread",
+    source: MAIL_THREAD_AGGREGATE_TYPE,
+    table: mailThreadsProjectionTable,
+    entity: mailThreadEntity,
+    apply: {
+      [MAIL_THREAD_UPDATED_EVENT_QN]: applyMailThreadUpdated,
+    },
+  });
+
+  // Plugin extension-point — Provider registrieren sich via
+  // r.useExtension("inboundMailProvider", "<key>", plugin).
+  r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
+    onRegister: () => {
+      // No side-effects at register-time — Lookup läuft zur Laufzeit
+      // über resolveInboundProviderForKey/-Account.
+    },
+  });
+
+  // Sync-Maschinerie: hochfrequenter Tick-State, bewusst NICHT
+  // event-sourced — r.unmanagedTable hält die Migration-DDL, nimmt die
+  // Tabellen aber aus dem Projection-Rebuild (#494/#498-Klasse).
+  r.unmanagedTable(syncCursorTable, {
+    reason: "read_side.mail_sync_cursors_direct_write",
+  });
+  r.unmanagedTable(seenMessageTable, {
+    reason: "read_side.mail_seen_messages_direct_write",
+  });
+
+  // Write-Handler:
+  //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
+  //   - connect/update/disconnect-account: Lifecycle
+  r.writeHandler(ingestMessageHandler);
+  r.writeHandler(connectAccountHandler);
+  r.writeHandler(updateAccountHandler);
+  r.writeHandler(disconnectAccountHandler);
+
+  // List-Queries (PII-decrypted, scope-gefiltert).
+  r.queryHandler(listAccountsQuery);
+  r.queryHandler(listMessagesQuery);
+
+  // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
+  // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
+  r.useExtension(EXT_TENANT_DATA, "mail-account", {
+    destroy: mailAccountTenantDestroyHook,
+  });
+  r.useExtension(EXT_TENANT_DATA, "inbound-message", {
+    destroy: inboundMessageTenantDestroyHook,
+  });
+  r.useExtension(EXT_TENANT_DATA, "mail-thread", {
+    destroy: mailThreadTenantDestroyHook,
+  });
+});

package/src/inbound-mail-foundation/handlers/account-state.ts

@@ -0,0 +1,23 @@
+// Geteilter State-Loader für update-account / disconnect-account.
+//
+// Die mail-account-Events sind full-snapshots (Muster billing-foundation:
+// "Alle nutzen denselben payload-shape, der event-type taggt was
+// passiert ist") — ein Übergangs-Handler lädt den letzten Snapshot,
+// merged seine Delta-Felder rein und appendet den neuen Snapshot.
+//
+// **PII-Disziplin:** `address` steht im geladenen Payload bereits als
+// Ciphertext und wird 1:1 durchkopiert — NIE re-encrypten (würde bei
+// fehlendem KMS decrypt erzwingen bzw. Double-Encryption produzieren).
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MailAccountEventPayload } from "../events";
+
+export async function loadCurrentMailAccountPayload(
+  ctx: Pick<HandlerContext, "loadAggregate">,
+  accountId: string,
+): Promise<MailAccountEventPayload | undefined> {
+  const events = await ctx.loadAggregate(accountId);
+  const last = events[events.length - 1];
+  // @cast-boundary engine-payload — eigene events, shape via defineEvent
+  return last?.payload as MailAccountEventPayload | undefined;
+}

package/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -0,0 +1,112 @@
+// connect-account — Tenant-Admin verbindet ein Postfach. Legt den
+// mail-account-Stream an (aggregateId = random uuid = accountId =
+// Secret-Slot-Key für IMAP-Passwort/OAuth-Refresh-Token).
+//
+// **Was hier NICHT passiert:**
+//   - Kein Secret-Write: IMAP-Credentials laufen über den secrets-Pfad,
+//     OAuth-Tokens über die generischen /inbound-mail/oauth-Routen —
+//     beides VOR bzw. NACH diesem Call, nie durch den Handler-Payload
+//     (Plain-Passwörter gehören nicht in einen Write-Payload, der im
+//     Dispatcher-Log landen kann).
+//   - Kein Verbindungs-Test: der Watch-Supervisor probiert den ersten
+//     fetch und schaltet bei Fehler via update-account auf auth_error —
+//     der Connect bleibt schnell und offline-fähig (Test-Ergebnis kommt
+//     asynchron als Status-Übergang).
+
+import {
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { InboundMailAccountStatuses, InboundMailAuthMethods } from "../constants";
+import { MAIL_ACCOUNT_PII_FIELDS, mailAccountEntity } from "../entities";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events";
+
+export const connectAccountSchema = z.object({
+  /** Provider-Key wie an der Extension registriert ("imap",
+   *  "m365-graph", "gmail-rest"). */
+  provider: z.string().min(1).max(50),
+  authMethod: z.enum([
+    InboundMailAuthMethods.password,
+    InboundMailAuthMethods.xoauth2,
+    InboundMailAuthMethods.oauth,
+  ]),
+  displayName: z.string().max(200),
+  /** Postfach-Adresse, Plaintext — wird hier encrypted. */
+  address: z.string().min(1).max(320),
+  /** "shared" = tenant-geteilt (info@) · "user" = persönliches Postfach
+   *  des Callers (ownerUserId wird aus der Session gezogen, nie aus dem
+   *  Payload — kein Fremd-Claiming). */
+  scope: z.enum(["shared", "user"]),
+  /** NUR für den programmatic OAuth-Callback-Pfad (SystemAdmin): dort
+   *  ist der Dispatcher-User ein SystemUser, der echte Owner steht im
+   *  HMAC-verifizierten state. Tenant-Caller dürfen das Feld nicht
+   *  setzen (Fremd-Claiming-Sperre im Handler). */
+  ownerUserIdOverride: z.string().max(36).nullable().optional(),
+});
+type ConnectAccountPayload = z.infer<typeof connectAccountSchema>;
+
+export const connectAccountHandler: WriteHandlerDef = {
+  name: "connect-account",
+  schema: connectAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as ConnectAccountPayload;
+    const tenantId = event.user.tenantId;
+    const accountId = crypto.randomUUID();
+
+    if (payload.ownerUserIdOverride !== undefined && !event.user.roles.includes("SystemAdmin")) {
+      return failUnprocessable("owner_override_requires_system_admin");
+    }
+    const ownerUserId =
+      payload.ownerUserIdOverride !== undefined
+        ? payload.ownerUserIdOverride
+        : payload.scope === "user"
+          ? event.user.id
+          : null;
+
+    // PII-Encrypt der Adresse vor dem append — einziger Write-Pfad auf
+    // den Stream, deckt Event-Log UND Projection ab (#800-Muster).
+    const piiKms = configuredPiiSubjectKms();
+    const plainPii = { tenantId, address: payload.address };
+    const encryptedFields = piiKms
+      ? await encryptPiiFieldValues(plainPii, mailAccountEntity, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:connect-account:${accountId}`,
+          tenantId,
+        })
+      : plainPii;
+
+    const eventPayload: MailAccountEventPayload = {
+      provider: payload.provider,
+      authMethod: payload.authMethod,
+      ownerUserId,
+      displayName: payload.displayName,
+      address: encryptedFields["address"] as string,
+      // active ab Connect — der Supervisor greift den Account beim
+      // nächsten Tick auf und degradiert ihn bei Credential-Fehlern.
+      status: InboundMailAccountStatuses.active,
+      watchState: "idle",
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: payload.provider,
+      reason: "connect_flow",
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return { isSuccess: true as const, data: { accountId } };
+  },
+};

package/src/inbound-mail-foundation/handlers/disconnect-account.write.ts

@@ -0,0 +1,69 @@
+// disconnect-account — Tenant-Admin trennt ein Postfach. Stream bleibt
+// (Audit-Historie), Status wird disconnected, der Watch-Supervisor
+// überspringt den Account ab dem nächsten Tick. Secret-Cleanup (IMAP-
+// Passwort/Refresh-Token im Slot accountId) macht der Aufrufer-Flow —
+// der Handler fasst den secrets-Pfad nicht an.
+//
+// Idempotent: disconnect auf bereits disconnected Account ist ein
+// success-no-op (kein zweites Event) — Doppelklick-/Retry-freundlich.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { InboundMailAccountStatuses } from "../constants";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events";
+import { loadCurrentMailAccountPayload } from "./account-state";
+
+export const disconnectAccountSchema = z.object({
+  accountId: z.uuid(),
+  reason: z.string().min(1).max(100).default("tenant_admin"),
+});
+type DisconnectAccountPayload = z.infer<typeof disconnectAccountSchema>;
+
+export const disconnectAccountHandler: WriteHandlerDef = {
+  name: "disconnect-account",
+  schema: disconnectAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as DisconnectAccountPayload;
+
+    const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+    if (!current) {
+      return failNotFound("mail-account", payload.accountId);
+    }
+    if (current.status === InboundMailAccountStatuses.disconnected) {
+      return {
+        isSuccess: true as const,
+        data: { accountId: payload.accountId, alreadyDisconnected: true as const },
+      };
+    }
+
+    const eventPayload: MailAccountEventPayload = {
+      ...current,
+      status: InboundMailAccountStatuses.disconnected,
+      watchState: "idle",
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: current.provider,
+      reason: payload.reason,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { accountId: payload.accountId, alreadyDisconnected: false as const },
+    };
+  },
+};

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -0,0 +1,279 @@
+// ingest-message — programmatic entry-point für Provider-Plugins
+// (watch-callback + fetchSince-Sync). Nimmt eine normalisierte
+// RawInboundMessage und macht atomic in EINER TX:
+//
+//   1. Idempotency-Check (cheap: read_mail_seen_messages; Defense-in-
+//      depth: Stream-Existenz auf der deterministic aggregateId).
+//   2. threadKey-Normalisierung (Provider-Thread-ID bevorzugt, sonst
+//      References-Chain-Root, sonst Message-ID = Single-Message-Thread).
+//   3. PII-Encrypt (from/to/cc/subject/snippet) VOR dem append —
+//      Event-Log UND Projection tragen Ciphertext (#800-Muster).
+//   4. inbound-message-received-append (Inline-Projection schreibt
+//      read_inbound_messages in derselben TX).
+//   5. Thread-Rollup: mail-thread-updated-append mit neu berechnetem
+//      Snapshot (count+1, max(lastMessageAt)) — die apply ist ein
+//      dummer UPSERT.
+//   6. seen-message-Dedup-Anchor einfügen.
+//
+// SystemAdmin-only: Aufrufer ist der Watch/Sync-Supervisor bzw. der
+// Poll-Cron mit programmatic SystemUser — nie ein Tenant-Request.
+
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { inboundMessageAggregateId, mailThreadAggregateId } from "../aggregate-id";
+import {
+  INBOUND_MESSAGE_PII_FIELDS,
+  inboundMessageEntity,
+  MAIL_THREAD_PII_FIELDS,
+  mailThreadEntity,
+  seenMessageTable,
+} from "../entities";
+import {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+  type InboundMessageEventHeaders,
+  type InboundMessageEventPayload,
+  MAIL_THREAD_AGGREGATE_TYPE,
+  MAIL_THREAD_UPDATED_EVENT_QN,
+  type MailThreadEventPayload,
+} from "../events";
+
+// =============================================================================
+// Input-Schema — der normalisierte Provider-Output (RawInboundMessage,
+// types.ts) + Envelope (accountId/providerName/providerCursor). rawMime
+// ist hier bewusst NICHT dabei: der Aufrufer persisted den Body VOR dem
+// ingest-Call nach file-foundation und übergibt nur bodyRef — der
+// Handler-Payload bleibt blob-frei (Event-Store-Disziplin).
+// =============================================================================
+
+export const ingestMessageSchema = z.object({
+  accountId: z.uuid(),
+  /** Scope-Vererbung vom Account — der Supervisor kennt den
+   *  MailAccountRecord und reicht ownerUserId durch. */
+  ownerUserId: z.string().max(36).nullable(),
+  providerName: z.string().min(1).max(50),
+  /** Provider-native Message-ID — Idempotency-Anchor mit accountId. */
+  providerMessageId: z.string().min(1).max(500),
+  /** RFC-5322 Message-ID ohne <>; null → deterministischer Ersatz. */
+  messageIdHeader: z.string().min(1).max(500).nullable(),
+  providerThreadId: z.string().min(1).max(500).nullable(),
+  /** References/In-Reply-To-Chain, älteste zuerst. */
+  references: z.array(z.string().min(1).max(500)).max(200),
+  from: z.string().min(1).max(2000),
+  to: z.array(z.string().max(2000)).max(200),
+  cc: z.array(z.string().max(2000)).max(200),
+  subject: z.string().max(4000),
+  snippet: z.string().max(4000),
+  receivedAtIso: z.string().min(1),
+  /** file-foundation-Ref; leer im snippet-only-Mode. */
+  bodyRef: z.string().max(500),
+  scope: z.string().min(1).max(200),
+  /** Cursor-Snapshot zum Ingest-Zeitpunkt — Debug/Replay, landet in
+   *  metadata.headers, nie im payload. */
+  providerCursor: z.string().max(2000),
+});
+type IngestMessagePayload = z.infer<typeof ingestMessageSchema>;
+
+/**
+ * threadKey-Normalisierung (Plan §3.2):
+ *   1. Provider-Thread-ID falls vorhanden — provider-präfixed, damit
+ *      IMAP-References-Keys und Graph-conversationIds nie kollidieren.
+ *   2. Sonst Root der References-Chain (älteste Message-ID = der
+ *      Thread-Anker, den alle Replies teilen).
+ *   3. Sonst die eigene Message-ID → Single-Message-Thread; ein späteres
+ *      Reply trägt sie als References-Root und landet im selben Thread.
+ */
+function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: string): string {
+  if (p.providerThreadId) return `${p.providerName}:${p.providerThreadId}`.slice(0, 500);
+  const referencesRoot = p.references[0];
+  if (referencesRoot) return `mid:${referencesRoot}`.slice(0, 500);
+  return `mid:${effectiveMessageIdHeader}`.slice(0, 500);
+}
+
+export const ingestMessageHandler: WriteHandlerDef = {
+  name: "ingest-message",
+  schema: ingestMessageSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as IngestMessagePayload;
+    const tenantId = event.user.tenantId;
+    const messageAggId = inboundMessageAggregateId(payload.accountId, payload.providerMessageId);
+
+    // ---------------------------------------------------------------
+    // 1. Idempotency. Cheap path zuerst: Dedup-Anchor-Row. Der
+    //    Stream-Check dahinter ist Defense-in-depth für den Fall dass
+    //    ein früherer ingest NACH dem append aber VOR dem seen-insert
+    //    gestorben ist (kann in einer TX nicht passieren — aber der
+    //    Check ist billig und macht den Handler rebuild-robust falls
+    //    read_mail_seen_messages je getruncated wird).
+    // ---------------------------------------------------------------
+    const seenRows = await selectMany(ctx.db.raw, seenMessageTable, {
+      accountId: payload.accountId,
+      providerMessageId: payload.providerMessageId,
+    });
+    if (seenRows.length > 0) {
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
+      };
+    }
+    const existingEvents = await ctx.loadAggregate(messageAggId);
+    if (existingEvents.length > 0) {
+      // Stream existiert, Anchor fehlte → Anchor nachziehen, dann raus.
+      await insertOne(ctx.db.raw, seenMessageTable, {
+        tenantId,
+        accountId: payload.accountId,
+        providerMessageId: payload.providerMessageId,
+        seenAt: Temporal.Now.instant().toString(),
+      });
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
+      };
+    }
+
+    // ---------------------------------------------------------------
+    // 2. messageIdHeader-Fallback + threadKey.
+    // ---------------------------------------------------------------
+    const effectiveMessageIdHeader = payload.messageIdHeader ?? `kumiko-inbound:${messageAggId}`;
+    const threadKey = buildThreadKey(payload, effectiveMessageIdHeader);
+    const threadAggId = mailThreadAggregateId(tenantId, threadKey);
+
+    // ---------------------------------------------------------------
+    // 3. PII-Encrypt. to/cc werden VOR encryption JSON-stringified —
+    //    im Payload steht der Ciphertext-String, nicht das Array
+    //    (primitives only, upcaster-safe). Kein KMS konfiguriert =
+    //    plaintext-passthrough (Engine-off-Verhalten, Muster
+    //    billing-foundation process-event #724/#800).
+    // ---------------------------------------------------------------
+    const piiKms = configuredPiiSubjectKms();
+    const messagePlainPii = {
+      tenantId,
+      from: payload.from,
+      to: JSON.stringify(payload.to),
+      cc: JSON.stringify(payload.cc),
+      subject: payload.subject,
+      snippet: payload.snippet,
+    };
+    const encryptedMessageFields = piiKms
+      ? await encryptPiiFieldValues(
+          messagePlainPii,
+          inboundMessageEntity,
+          INBOUND_MESSAGE_PII_FIELDS,
+          piiKms,
+          {
+            requestId: `inbound-mail-foundation:ingest-message:${messageAggId}`,
+            tenantId,
+          },
+        )
+      : messagePlainPii;
+
+    // ---------------------------------------------------------------
+    // 4. inbound-message-received-append. Inline-Projection schreibt
+    //    read_inbound_messages in derselben TX.
+    // ---------------------------------------------------------------
+    const messageEventPayload: InboundMessageEventPayload = {
+      accountId: payload.accountId,
+      ownerUserId: payload.ownerUserId,
+      messageIdHeader: effectiveMessageIdHeader,
+      threadKey,
+      from: encryptedMessageFields["from"] as string,
+      to: encryptedMessageFields["to"] as string,
+      cc: encryptedMessageFields["cc"] as string,
+      subject: encryptedMessageFields["subject"] as string,
+      snippet: encryptedMessageFields["snippet"] as string,
+      receivedAtIso: payload.receivedAtIso,
+      bodyRef: payload.bodyRef,
+      scope: payload.scope,
+    };
+    const messageHeaders: InboundMessageEventHeaders = {
+      providerMessageId: payload.providerMessageId,
+      providerName: payload.providerName,
+      providerCursor: payload.providerCursor,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: messageAggId,
+      aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+      type: INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+      payload: messageEventPayload,
+      headers: messageHeaders,
+    });
+
+    // ---------------------------------------------------------------
+    // 5. Thread-Rollup. Der Handler berechnet den NEUEN Snapshot
+    //    (count+1, max(lastMessageAt)) — die apply ist ein dummer
+    //    UPSERT und bleibt replay-idempotent. lastMessageAtIso ist
+    //    kein PII (Zeitpunkt), damit plaintext-vergleichbar; subject
+    //    wird frisch encrypted (jede Thread-Version trägt das Subject
+    //    der jüngsten Mail).
+    //
+    //    **Kein Lost-Update-Fenster:** loadAggregate + append laufen in
+    //    derselben TX; zwei parallele ingests auf denselben Thread
+    //    serialisiert der event-store über die Stream-Version.
+    // ---------------------------------------------------------------
+    const threadEvents = await ctx.loadAggregate(threadAggId);
+    const lastThreadEvent = threadEvents[threadEvents.length - 1];
+    // @cast-boundary engine-payload — eigene events, shape via defineEvent
+    const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
+    const previousCount = previousThread?.messageCount ?? 0;
+    const previousLastAt = previousThread?.lastMessageAtIso ?? "";
+    const newLastAt =
+      payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
+
+    const threadPlainPii = { tenantId, subject: payload.subject };
+    const encryptedThreadFields = piiKms
+      ? await encryptPiiFieldValues(
+          threadPlainPii,
+          mailThreadEntity,
+          MAIL_THREAD_PII_FIELDS,
+          piiKms,
+          {
+            requestId: `inbound-mail-foundation:ingest-message:thread:${threadAggId}`,
+            tenantId,
+          },
+        )
+      : threadPlainPii;
+
+    const threadEventPayload: MailThreadEventPayload = {
+      threadKey,
+      subject: encryptedThreadFields["subject"] as string,
+      lastMessageAtIso: newLastAt,
+      messageCount: previousCount + 1,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: threadAggId,
+      aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
+      type: MAIL_THREAD_UPDATED_EVENT_QN,
+      payload: threadEventPayload,
+      headers: messageHeaders,
+    });
+
+    // ---------------------------------------------------------------
+    // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt
+    //    der Handler, rollt alles zusammen zurück.
+    // ---------------------------------------------------------------
+    await insertOne(ctx.db.raw, seenMessageTable, {
+      tenantId,
+      accountId: payload.accountId,
+      providerMessageId: payload.providerMessageId,
+      seenAt: Temporal.Now.instant().toString(),
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        duplicate: false as const,
+        inboundMessageAggregateId: messageAggId,
+        threadAggregateId: threadAggId,
+        threadKey,
+      },
+    };
+  },
+};