@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -0,0 +1,333 @@
+// 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: store_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). Savepoint-scoped
+//      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
+//      messageAggId returns { duplicate: true } instead of failing the 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 { countWhere, 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 { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+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";
+import { inboundMessagesProjectionTable } from "../projection";
+
+// =============================================================================
+// 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);
+}
+
+const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
+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
+    //    store_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,
+    };
+    const messageAppend = await ctx.tryAppendEvent({
+      aggregateId: messageAggId,
+      aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+      type: INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+      payload: messageEventPayload,
+      headers: messageHeaders,
+    });
+    if (!messageAppend.ok) {
+      // Lost the race against a concurrent ingest for the same messageAggId
+      // (Watch-Push vs. Poll-Reconciliation overlap). The winner already
+      // writes thread-rollup + seen-anchor for this message — steps 5+6
+      // skip here. tryAppendEvent's savepoint keeps this TX usable despite
+      // the caught VersionConflictError (see ctx.tryAppendEvent doc).
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
+      };
+    }
+
+    // ---------------------------------------------------------------
+    // 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
+    //    ctx.tryAppendEvent in a bounded retry loop — the apply stays a
+    //    dumb, replay-idempotent UPSERT. lastMessageAtIso is not PII (a
+    //    timestamp), so it stays plaintext-comparable; subject is
+    //    encrypted once up front (constant across retries, doesn't
+    //    depend on the thread's prior state).
+    //
+    //    messageCount deliberately does NOT come from a previously loaded
+    //    threadEvents snapshot (previousCount+1): two concurrent ingests
+    //    on the same thread (Watch-Push vs. Poll-Reconciliation overlap,
+    //    or two different messages of the same thread arriving at once)
+    //    can both read the same stream version before either commits.
+    //    tryAppendEvent's fresh version-read at append time makes the
+    //    loser's append fail with a VersionConflictError ONLY when the
+    //    other TX's commit lands between this reload and the append's own
+    //    version check — so we retry: reload the thread stream, recompute
+    //    the live row-count and lastMessageAt, and append again. If the
+    //    other TX instead commits in the gap between the countWhere below
+    //    and the append's version-read, the version check sees the
+    //    already-bumped stream and appends without conflict — but with the
+    //    stale row-count this countWhere captured before the concurrent
+    //    insert. That write still lands (messageCount can undercount by
+    //    one round), it is not eliminated by this retry loop; the next
+    //    ingest on the thread re-counts and self-corrects. Unlike step 4,
+    //    a lost version-conflict race here must NOT be treated as a no-op
+    //    duplicate — skipping would leave this message's contribution to
+    //    messageCount/lastMessageAt out of the thread forever. Exhausting
+    //    all attempts throws, rolling back the whole TX (including the
+    //    step-4 message append) for a clean re-ingest on the next poll —
+    //    never return success with a stale snapshot.
+    //
+    //    A true race-free read+append (e.g. SELECT ... FOR UPDATE or an
+    //    advisory lock on threadAggId) would close the countWhere→append
+    //    gap above and is deliberately not part of this fix — two writers
+    //    (watch + poll) make self-correcting drift an acceptable trade for
+    //    now.
+    // ---------------------------------------------------------------
+    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;
+
+    let threadAppendOk = false;
+    for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
+      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 previousLastAt = previousThread?.lastMessageAtIso ?? "";
+      const newLastAt =
+        payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
+      const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
+        tenantId,
+        threadKey,
+      });
+
+      const threadEventPayload: MailThreadEventPayload = {
+        threadKey,
+        subject: encryptedThreadFields["subject"] as string,
+        lastMessageAtIso: newLastAt,
+        messageCount,
+      };
+      const threadAppend = await ctx.tryAppendEvent({
+        aggregateId: threadAggId,
+        aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
+        type: MAIL_THREAD_UPDATED_EVENT_QN,
+        payload: threadEventPayload,
+        headers: messageHeaders,
+      });
+      threadAppendOk = threadAppend.ok;
+    }
+    if (!threadAppendOk) {
+      throw new InternalError({
+        message: `ingest-message: thread-rollup append for "${threadAggId}" lost the version-conflict race ${THREAD_ROLLUP_MAX_ATTEMPTS} times in a row — aborting for a clean re-ingest instead of persisting a stale messageCount.`,
+      });
+    }
+
+    // ---------------------------------------------------------------
+    // 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,
+      },
+    };
+  },
+};

package/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -0,0 +1,44 @@
+// list-accounts — tenant-scoped Liste der verbundenen Postfächer fürs
+// Connect-/Settings-UI. PII (address) wird beim Read decrypted (Muster
+// billing-foundation list-subscriptions).
+//
+// **Scope-Sichtbarkeit (Plan Entscheidung 2):** shared-Postfächer
+// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
+// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Filter läuft
+// in-memory nach dem tenant-scoped select — Volumen ist die Anzahl
+// verbundener Postfächer eines Tenants (einstellig bis zweistellig).
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { MAIL_ACCOUNT_PII_FIELDS } from "../entities";
+import { mailAccountsProjectionTable } from "../projection";
+import { isVisibleToCaller } from "./scope-visibility";
+
+const listAccountsSchema = z.object({}).strict();
+
+export const listAccountsQuery: QueryHandlerDef = {
+  name: "account:list",
+  schema: listAccountsSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  handler: async (_query, ctx) => {
+    const allRows = await selectMany(ctx.db.raw, mailAccountsProjectionTable, {
+      tenantId: ctx.user.tenantId,
+    });
+    const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+    const piiKms = configuredPiiSubjectKms();
+    if (!piiKms) return { rows };
+    const decryptedRows = await Promise.all(
+      rows.map((row) =>
+        decryptPiiFieldValues(row as Record<string, unknown>, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
+        }),
+      ),
+    );
+    return { rows: decryptedRows };
+  },
+};

package/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -0,0 +1,58 @@
+// list-messages — tenant-scoped Message-Liste (Inbox-Cockpit).
+// Optionale Filter: accountId (ein Postfach), threadKey (eine
+// Konversation), scope (Folder-Hint). PII (from/to/cc/subject/snippet)
+// wird beim Read decrypted; to/cc bleiben JSON-stringified strings —
+// der Client parsed sie (dokumentiert im Event-Payload).
+//
+// Bewusst KEINE Pagination in V1: die Projection ist tenant-scoped und
+// das Inbox-Cockpit lädt begrenzte Zeiträume; ein `limit`-Feld ist
+// vorwärtskompatibel ergänzbar ohne den QN zu brechen.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities";
+import { inboundMessagesProjectionTable } from "../projection";
+import { isVisibleToCaller } from "./scope-visibility";
+
+const listMessagesSchema = z
+  .object({
+    accountId: z.uuid().optional(),
+    threadKey: z.string().min(1).max(500).optional(),
+    scope: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+type ListMessagesPayload = z.infer<typeof listMessagesSchema>;
+
+export const listMessagesQuery: QueryHandlerDef = {
+  name: "message:list",
+  schema: listMessagesSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  handler: async (query, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = query.payload as ListMessagesPayload;
+    const filter: Record<string, unknown> = { tenantId: ctx.user.tenantId };
+    if (payload.accountId) filter["accountId"] = payload.accountId;
+    if (payload.threadKey) filter["threadKey"] = payload.threadKey;
+    if (payload.scope) filter["scope"] = payload.scope;
+
+    const allRows = await selectMany(ctx.db.raw, inboundMessagesProjectionTable, filter);
+    // Scope-Sichtbarkeit (Plan Entscheidung 2): Messages persönlicher
+    // Postfächer nur für Owner + TenantAdmin/SystemAdmin.
+    const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+    const piiKms = configuredPiiSubjectKms();
+    if (!piiKms) return { rows };
+    const decryptedRows = await Promise.all(
+      rows.map((row) =>
+        decryptPiiFieldValues(row as Record<string, unknown>, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:list-messages:${ctx.user.tenantId}`,
+        }),
+      ),
+    );
+    return { rows: decryptedRows };
+  },
+};

package/src/inbound-mail-foundation/handlers/scope-visibility.ts

@@ -0,0 +1,14 @@
+// Scope-Sichtbarkeit (Plan Entscheidung 2): shared-Rows
+// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
+// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Gilt identisch
+// für read_mail_accounts und read_inbound_messages (Scope-Vererbung).
+
+export function isVisibleToCaller(
+  row: unknown,
+  user: { readonly id: string; readonly roles: readonly string[] },
+): boolean {
+  const owner = (row as Record<string, unknown>)["ownerUserId"];
+  if (owner == null || owner === "") return true;
+  if (owner === user.id) return true;
+  return user.roles.includes("TenantAdmin") || user.roles.includes("SystemAdmin");
+}

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

@@ -0,0 +1,78 @@
+// update-account — Account-Status-Übergänge: Watch-Supervisor meldet
+// error/backoff, OAuth-Refresh scheitert (auth_error), Tenant-Admin
+// re-enabled nach Credential-Fix. Full-snapshot-Event: lädt den letzten
+// Stand, merged die Delta-Felder, appendet den neuen Snapshot.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { InboundMailAccountStatuses } from "../constants";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events";
+import { loadCurrentMailAccountPayload } from "./account-state";
+
+export const updateAccountSchema = z.object({
+  accountId: z.uuid(),
+  status: z
+    .enum([
+      InboundMailAccountStatuses.active,
+      InboundMailAccountStatuses.authError,
+      InboundMailAccountStatuses.degraded,
+    ])
+    .optional(),
+  /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
+  watchState: z.string().max(100).optional(),
+  displayName: z.string().max(200).optional(),
+  /** Audit-Grund für metadata.headers ("watch_supervisor",
+   *  "oauth_refresh", "tenant_admin"). */
+  reason: z.string().min(1).max(100),
+});
+type UpdateAccountPayload = z.infer<typeof updateAccountSchema>;
+
+export const updateAccountHandler: WriteHandlerDef = {
+  name: "update-account",
+  schema: updateAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as UpdateAccountPayload;
+
+    const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+    if (!current) {
+      return failNotFound("mail-account", payload.accountId);
+    }
+    if (current.status === InboundMailAccountStatuses.disconnected) {
+      // Getrennte Accounts sind final — Re-Enable läuft über einen
+      // frischen connect (neuer Stream, neuer Secret-Slot). Verhindert
+      // dass ein nachzügelnder Supervisor-Tick einen disconnected
+      // Account wieder auf active hebt (Race Disconnect vs. Poll).
+      return failUnprocessable("account_disconnected", { accountId: payload.accountId });
+    }
+
+    // Merge: address/provider/authMethod kommen 1:1 aus dem letzten
+    // Snapshot (address bleibt Ciphertext — nie re-encrypten).
+    const eventPayload: MailAccountEventPayload = {
+      ...current,
+      ...(payload.status !== undefined ? { status: payload.status } : {}),
+      ...(payload.watchState !== undefined ? { watchState: payload.watchState } : {}),
+      ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: current.provider,
+      reason: payload.reason,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return { isSuccess: true as const, data: { accountId: payload.accountId } };
+  },
+};

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

@@ -0,0 +1,97 @@
+// Public API of the inbound-mail-foundation bundled-feature.
+
+export {
+  inboundMessageAggregateId,
+  mailThreadAggregateId,
+} from "./aggregate-id";
+export {
+  createInboundMailConnectRoutes,
+  type InboundMailConnectRoutes,
+  type InboundMailConnectRoutesDeps,
+} from "./connect-routes";
+export {
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  INBOUND_MAIL_PROVIDER_EXTENSION,
+  type InboundMailAccountStatus,
+  InboundMailAccountStatuses,
+  type InboundMailAuthMethod,
+  InboundMailAuthMethods,
+  InboundMailFoundationHandlers,
+  InboundMailFoundationQueries,
+  inboundCredentialSecretKey,
+} from "./constants";
+export {
+  INBOUND_MESSAGE_PII_FIELDS,
+  inboundMessageEntity,
+  MAIL_ACCOUNT_PII_FIELDS,
+  MAIL_THREAD_PII_FIELDS,
+  mailAccountEntity,
+  mailThreadEntity,
+  seenMessageEntity,
+  seenMessageTable,
+  syncCursorEntity,
+  syncCursorTable,
+} from "./entities";
+export {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+  INBOUND_MESSAGE_RECEIVED_EVENT_SHORT,
+  type InboundMessageEventHeaders,
+  type InboundMessageEventPayload,
+  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,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+  type MailThreadEventPayload,
+  mailAccountEventPayloadSchema,
+  mailThreadEventPayloadSchema,
+} from "./events";
+export { inboundMailFoundationFeature } from "./feature";
+export {
+  type OAuthStatePayload,
+  signOAuthState,
+  type VerifyOAuthStateResult,
+  verifyOAuthState,
+} from "./oauth-state";
+export {
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  mailThreadsProjectionTable,
+} from "./projection";
+export {
+  resolveInboundProviderForAccount,
+  resolveInboundProviderForKey,
+} from "./provider-factory";
+export {
+  InboundAuthError,
+  InboundCursorInvalidError,
+  type InboundFetchResult,
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  type InboundOAuthFlow,
+  InboundRateLimitError,
+  InboundTransientError,
+  isInboundAuthError,
+  isInboundCursorInvalidError,
+  isInboundMailProviderPlugin,
+  isInboundRateLimitError,
+  isInboundTransientError,
+  type MailAccountRecord,
+  type OAuthTokenSet,
+  type RawInboundMessage,
+  type SyncCursorPayload,
+} from "./types";
+export {
+  createInboundMailSupervisor,
+  type InboundMailSupervisor,
+  type InboundMailSupervisorDeps,
+} from "./watch-supervisor";