@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

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

@@ -7,10 +7,12 @@ export declare const MAIL_ACCOUNT_UPDATED_EVENT_SHORT: "mail-account-updated";
 export declare const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT: "mail-account-disconnected";
 export declare const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT: "inbound-message-received";
 export declare const MAIL_THREAD_UPDATED_EVENT_SHORT: "mail-thread-updated";
+export declare const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT: "inbound-message-content-fetched";
 export declare const MAIL_ACCOUNT_CONNECTED_EVENT_QN: "inbound-mail-foundation:event:mail-account-connected";
 export declare const MAIL_ACCOUNT_UPDATED_EVENT_QN: "inbound-mail-foundation:event:mail-account-updated";
 export declare const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN: "inbound-mail-foundation:event:mail-account-disconnected";
 export declare const INBOUND_MESSAGE_RECEIVED_EVENT_QN: "inbound-mail-foundation:event:inbound-message-received";
+export declare const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN: "inbound-mail-foundation:event:inbound-message-content-fetched";
 export declare const MAIL_THREAD_UPDATED_EVENT_QN: "inbound-mail-foundation:event:mail-thread-updated";
 export declare const mailAccountEventPayloadSchema: z.ZodObject<{
     provider: z.ZodString;
@@ -25,9 +27,51 @@ export declare const mailAccountEventPayloadSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     watchState: z.ZodString;
+    lastError: z.ZodNullable<z.ZodString>;
+    trustedAuthservId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type MailAccountEventPayload = z.infer<typeof mailAccountEventPayloadSchema>;
+export declare const INBOUND_CONTENT_STATES: readonly ["complete", "snippet", "unavailable"];
+export type InboundContentState = (typeof INBOUND_CONTENT_STATES)[number];
+/** Why a message has no content: held back by the quarantine (retry possible), no file storage wired, or gone from the server. */
+export declare const INBOUND_CONTENT_UNAVAILABLE_REASONS: readonly ["quarantined", "no_file_storage", "gone_from_server"];
+export type InboundContentUnavailableReason = (typeof INBOUND_CONTENT_UNAVAILABLE_REASONS)[number];
+export declare const skippedAttachmentSchema: z.ZodObject<{
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    reason: z.ZodEnum<{
+        mail_too_large: "mail_too_large";
+        nesting_too_deep: "nesting_too_deep";
+        no_file_storage: "no_file_storage";
+        rejected: "rejected";
+        too_large: "too_large";
+    }>;
+}, z.core.$strip>;
 export declare const inboundMessageEventPayloadSchema: z.ZodObject<{
+    bodyText: z.ZodString;
+    bodyTextTruncated: z.ZodBoolean;
+    attachmentFileIds: z.ZodArray<z.ZodUUID>;
+    skippedAttachments: z.ZodArray<z.ZodObject<{
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        reason: z.ZodEnum<{
+            mail_too_large: "mail_too_large";
+            nesting_too_deep: "nesting_too_deep";
+            no_file_storage: "no_file_storage";
+            rejected: "rejected";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>;
+    contentState: z.ZodEnum<{
+        complete: "complete";
+        snippet: "snippet";
+        unavailable: "unavailable";
+    }>;
+    contentUnavailableReason: z.ZodNullable<z.ZodEnum<{
+        gone_from_server: "gone_from_server";
+        no_file_storage: "no_file_storage";
+        quarantined: "quarantined";
+    }>>;
     accountId: z.ZodUUID;
     ownerUserId: z.ZodNullable<z.ZodString>;
     messageIdHeader: z.ZodString;
@@ -40,8 +84,61 @@ export declare const inboundMessageEventPayloadSchema: z.ZodObject<{
     receivedAtIso: z.ZodString;
     bodyRef: z.ZodString;
     scope: z.ZodString;
+    senderAuthentication: z.ZodNullable<z.ZodObject<{
+        authservId: z.ZodString;
+        spf: z.ZodEnum<{
+            fail: "fail";
+            none: "none";
+            pass: "pass";
+            unknown: "unknown";
+        }>;
+        dkim: z.ZodEnum<{
+            fail: "fail";
+            none: "none";
+            pass: "pass";
+            unknown: "unknown";
+        }>;
+        dkimDomains: z.ZodArray<z.ZodString>;
+        dmarc: z.ZodEnum<{
+            fail: "fail";
+            none: "none";
+            pass: "pass";
+            unknown: "unknown";
+        }>;
+        fromDomain: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type InboundMessageEventPayload = z.infer<typeof inboundMessageEventPayloadSchema>;
+export declare const inboundMessageContentFetchedEventPayloadSchema: z.ZodObject<{
+    bodyText: z.ZodString;
+    bodyTextTruncated: z.ZodBoolean;
+    attachmentFileIds: z.ZodArray<z.ZodUUID>;
+    skippedAttachments: z.ZodArray<z.ZodObject<{
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        reason: z.ZodEnum<{
+            mail_too_large: "mail_too_large";
+            nesting_too_deep: "nesting_too_deep";
+            no_file_storage: "no_file_storage";
+            rejected: "rejected";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>;
+    contentState: z.ZodEnum<{
+        complete: "complete";
+        snippet: "snippet";
+        unavailable: "unavailable";
+    }>;
+    contentUnavailableReason: z.ZodNullable<z.ZodEnum<{
+        gone_from_server: "gone_from_server";
+        no_file_storage: "no_file_storage";
+        quarantined: "quarantined";
+    }>>;
+    accountId: z.ZodNullable<z.ZodUUID>;
+    ownerUserId: z.ZodNullable<z.ZodString>;
+    bodyRef: z.ZodString;
+}, z.core.$strip>;
+export type InboundMessageContentFetchedEventPayload = z.infer<typeof inboundMessageContentFetchedEventPayloadSchema>;
 export declare const mailThreadEventPayloadSchema: z.ZodObject<{
     threadKey: z.ZodString;
     subject: z.ZodString;

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

@@ -21,6 +21,7 @@
 //     (crypto-shredding, the billing-foundation pattern).
 import * as z from "zod";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.js";
+import { senderAuthenticationFieldSchema } from "./sender-auth.js";
 // Aggregate types for the event store.
 export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account";
 export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message";
@@ -32,10 +33,12 @@ export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated";
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected";
 export const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT = "inbound-message-received";
 export const MAIL_THREAD_UPDATED_EVENT_SHORT = "mail-thread-updated";
+export const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT = "inbound-message-content-fetched";
 export const MAIL_ACCOUNT_CONNECTED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_CONNECTED_EVENT_SHORT}`;
 export const MAIL_ACCOUNT_UPDATED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_UPDATED_EVENT_SHORT}`;
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT}`;
 export const INBOUND_MESSAGE_RECEIVED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_RECEIVED_EVENT_SHORT}`;
+export const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT}`;
 export const MAIL_THREAD_UPDATED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_THREAD_UPDATED_EVENT_SHORT}`;
 const accountStatusEnum = z.enum([
     InboundMailAccountStatuses.active,
@@ -65,7 +68,43 @@ export const mailAccountEventPayloadSchema = z.object({
     /** Provider-agnostic watch state ("idle", "watching", "backoff:3", ...)
      *  — an operational signal only, not PII. */
     watchState: z.string().max(100),
+    /** Why the mailbox is degraded (InboundMailLastErrors code); null while healthy. A string rather
+     *  than an enum, like authMethod, so a new code needs no upcaster. */
+    lastError: z.string().max(50).nullable(),
+    /** authserv-id (lower case) of the mailbox's own server; only an Authentication-Results header
+     *  with exactly this id is believed (sender-auth.ts). null = not set, no sender verdicts. */
+    trustedAuthservId: z.string().max(255).nullable(),
 });
+export const INBOUND_CONTENT_STATES = ["complete", "snippet", "unavailable"];
+/** Why a message has no content: held back by the quarantine (retry possible), no file storage wired, or gone from the server. */
+export const INBOUND_CONTENT_UNAVAILABLE_REASONS = [
+    "quarantined",
+    "no_file_storage",
+    "gone_from_server",
+];
+export const skippedAttachmentSchema = z.object({
+    mimeType: z.string().max(255),
+    size: z.number().int().min(0),
+    reason: z.enum([
+        "too_large",
+        "mail_too_large",
+        "rejected",
+        "no_file_storage",
+        "nesting_too_deep",
+    ]),
+});
+// Shared by inbound-message-received (v2+) and inbound-message-content-fetched.
+// bodyText is ciphertext: 32_000 characters become roughly 75 KB, hence the generous max.
+const inboundMessageContentShape = {
+    bodyText: z.string().max(200_000),
+    bodyTextTruncated: z.boolean(),
+    /** file-foundation FileRef ids (plaintext uuids). Attachments outlive the mail: apps turn them
+     *  into documents, so the retention sweep never deletes them. */
+    attachmentFileIds: z.array(z.uuid()).max(50),
+    skippedAttachments: z.array(skippedAttachmentSchema).max(200),
+    contentState: z.enum(INBOUND_CONTENT_STATES),
+    contentUnavailableReason: z.enum(INBOUND_CONTENT_UNAVAILABLE_REASONS).nullable(),
+};
 // ============================================================================
 // inbound-message stream — exactly ONE received event per message
 // ============================================================================
@@ -97,12 +136,28 @@ export const inboundMessageEventPayloadSchema = z.object({
     /** ISO instant — receipt time reported by the provider (INTERNALDATE or
      *  receivedDateTime), not ingest time. */
     receivedAtIso: z.string().min(1),
-    /** file-foundation reference to the raw body (MIME). Empty when the app
-     *  is mounted without body persistence (snippet-only mode). */
+    /** file-foundation reference to the original (.eml, or .html for HTML-only mails). Empty for
+     *  snippet-only mails and when no file storage is available. */
     bodyRef: z.string().max(500),
     /** Domain scope hint for downstream business processes — generic
      *  ("inbox", folder name), with NO app-specific semantics. */
     scope: z.string().max(200),
+    /** SPF/DKIM/DMARC as reported by the mailbox's own server; null when there is no trustworthy
+     *  statement. Not PII. */
+    senderAuthentication: senderAuthenticationFieldSchema,
+    ...inboundMessageContentShape,
+});
+// ============================================================================
+// Content of a message that was imported as snippet only and re-downloaded later.
+// Same aggregate as the received event; applies as an update of the projection row.
+// ============================================================================
+export const inboundMessageContentFetchedEventPayloadSchema = z.object({
+    /** Account and scope of the message, so a subscriber can route the event without loading the
+     *  stream. Null on events stored before v3: the stream id cannot be reversed to the account. */
+    accountId: z.uuid().nullable(),
+    ownerUserId: z.string().max(36).nullable(),
+    bodyRef: z.string().max(500),
+    ...inboundMessageContentShape,
 });
 // ============================================================================
 // mail-thread-Stream — Thread-Rollup pro (tenantId, threadKey)

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

@@ -1,3 +1,6 @@
-export declare function createInboundMailFoundationFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
-    readonly exports: void;
+import { type InboundMailRoleOptions } from "./mail-roles.ts";
+export declare function createInboundMailFoundationFeature(options?: InboundMailRoleOptions): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: {
+        roles: import("./mail-roles.ts").InboundMailRoles;
+    };
 };

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

@@ -1,63 +1,58 @@
 // kumiko-feature-version: 1
-//
-// inbound-mail-foundation — Plugin host for inbound e-mail
-// (inbox federation). Counterpart to mail-foundation (outbound): separate
-// extension points, separate state — architectural model is
-// file-foundation (the foundation owns state), not mail-transport.
-//
-// **Multi-provider from day one** (as with billing-foundation): NO global
-// `provider` config key. A tenant can connect IMAP and (later) M365/Gmail
-// mailboxes in parallel; the provider is specified per MailAccount.
+// inbound-mail-foundation: plugin host for inbound e-mail (inbox federation), the counterpart to
+// mail-foundation (outbound) with its own extension points and state. Modelled on file-foundation
+// (the foundation owns state), not on mail-transport.
 //
 // **What this foundation provides:**
-//   1. **Plugin API** for inbound providers via r.extendsRegistrar
-//      ("inboundMailProvider"): verify/fetch/oauth?/watch? (types.ts).
+//   1. **Plugin API** for providers via r.extendsRegistrar: verify/fetch/oauth?/watch? (types.ts).
 //   2. **3 event-sourced streams** — mail-account (lifecycle),
 //      inbound-message (exactly ONE received event per message, deterministic
 //      aggregateId ⇒ exactly-once despite at-least-once ingest),
-//      mail-thread (rollup). Full replayable history for later
-//      consumers (business processes: ticket, receipt, auto-reply).
-//   3. **Inline projections** into read_mail_accounts /
-//      read_inbound_messages / read_mail_threads (read-your-own-write).
+//      mail-thread (rollup), fully replayable for later consumers.
+//   3. **Inline projections** into read_mail_accounts/_inbound_messages/_mail_threads (RYOW).
 //   4. **Write/query handlers**: connect/update/disconnect-account,
 //      ingest-message (programmatic, SystemAdmin), account:list +
-//      message:list (PII-decrypted, scope-filtered).
-//   5. **createInboundMailConnectRoutes**: OAuth connect + anonymous
-//      callback (outside /api/*), with HMAC-signed state.
-//   6. **createInboundMailSupervisor**: app-wired watch (IDLE)
-//      supervisor with backoff + reconciliation poll.
+//      message:list (PII-decrypted; personal mail only for its owner).
 //
-// **What this foundation does NOT do:**
-//   - No business semantics (intent, ticket, assignment, read/
-//     completed) — those belong to the app consumer (for example, via an
-//     event job on inbound-message-received + its own projection).
-//   - No body blob in the event store: rawMime → file-foundation via
-//     the Supervisor-storeBody-Hook; the event carries only bodyRef.
-//   - No IMAP flag write-back (V1) — inbox status belongs to the consumer.
+// **Not here:** business semantics (intent, ticket, assignment, read/completed) belong to the
+// app consumer, for example an event job on inbound-message-received with its own projection.
 //
-// **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`
-// — encrypted BEFORE every event append (the only write path), event log AND
-// projections carry ciphertext; tenant-destroy shreds the subject key
-// (crypto-shredding, the same pattern as billing-foundation). The destroy
-// hook additionally archives all streams + deletes the rows.
+// **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`, encrypted BEFORE every
+// event append (the only write path), so event log AND projections carry ciphertext; tenant-destroy
+// shreds the subject key (crypto-shredding, as in billing-foundation) and its hook additionally
+// archives all streams and deletes the rows.
 import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
-import { createFileProviderForTenant, } from "@cosmicdrift/kumiko-framework/files";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.js";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity, seenMessageTable, syncCursorTable, } from "./entities.js";
-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.js";
-import { connectAccountHandler } from "./handlers/connect-account.write.js";
-import { disconnectAccountHandler } from "./handlers/disconnect-account.write.js";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN, INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT, INBOUND_MESSAGE_RECEIVED_EVENT_QN, INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageContentFetchedEventPayloadSchema, 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.js";
+import { createAcknowledgeQuarantineHandler } from "./handlers/acknowledge-quarantine.write.js";
+import { attachMessageContentHandler } from "./handlers/attach-message-content.write.js";
+import { createConnectAccountHandler } from "./handlers/connect-account.write.js";
+import { createDisconnectAccountHandler } from "./handlers/disconnect-account.write.js";
 import { ingestMessageHandler } from "./handlers/ingest-message.write.js";
-import { listAccountsQuery } from "./handlers/list-accounts.query.js";
-import { listMessagesQuery } from "./handlers/list-messages.query.js";
-import { updateAccountHandler } from "./handlers/update-account.write.js";
+import { createListAccountsQuery } from "./handlers/list-accounts.query.js";
+import { createListMessagesQuery } from "./handlers/list-messages.query.js";
+import { createListQuarantineQuery } from "./handlers/list-quarantine.query.js";
+import { markCredentialStoredHandler } from "./handlers/mark-credential-stored.write.js";
+import { createMessageContentQuery } from "./handlers/message-content.query.js";
+import { createMessageDetailQuery } from "./handlers/message-detail.query.js";
+import { createReactivateAccountHandler } from "./handlers/reactivate-account.write.js";
+import { createRetryQuarantinedMessageHandler } from "./handlers/retry-quarantined-message.write.js";
+import { createSetTrustedAuthservIdHandler } from "./handlers/set-trusted-authserv-id.write.js";
+import { createUpdateAccountHandler } from "./handlers/update-account.write.js";
 import { INBOUND_MAIL_FOUNDATION_I18N } from "./i18n.js";
+import { ingestFailureTable } from "./ingest-failures.js";
+import { resolveInboundMailRoles, roleDedupeOptions, } from "./mail-roles.js";
 import { registerMailboxProbe } from "./probe.js";
-import { applyInboundMessageReceived, applyMailAccountConnected, applyMailAccountDisconnected, applyMailAccountUpdated, applyMailThreadUpdated, inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";
-import { runInboundMailRetention } from "./retention-sweep.js";
-import { mailAccountEditScreen, mailAccountListScreen } from "./screens.js";
+import { applyInboundMessageContentFetched, applyInboundMessageReceived, applyMailAccountConnected, applyMailAccountDisconnected, applyMailAccountUpdated, applyMailThreadUpdated, inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";
+import { quarantineTable } from "./quarantine-entities.js";
+import { createMailQuarantineScreen } from "./quarantine-screens.js";
+import { registerInboundMailRetentionJob } from "./retention-job.js";
+import { createMailAccountScreens } from "./screens.js";
 import { INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON, inboundMessageTenantDestroyHook, mailAccountTenantDestroyHook, mailThreadTenantDestroyHook, } from "./tenant-destroy-hook.js";
-export function createInboundMailFoundationFeature() {
+import { registerMailAccountWakeConsumer } from "./wake-consumer.js";
+export function createInboundMailFoundationFeature(options = {}) {
+    const roles = resolveInboundMailRoles(options);
     return defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
         r.adoptsBundledLists();
         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) and send. `sendMailFromAccount(ctx, { accountId, message })` sends from a connected mailbox through its provider (From = the mailbox address, no fallback to the app sender) and answers typed failures (not configured, login rejected, server unreachable, rejected, invalid message); app write handlers call it, it is no endpoint of its own. 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.");
@@ -68,27 +63,79 @@ export function createInboundMailFoundationFeature() {
         });
         // The EXT_TENANT_DATA hook requires the tenant-lifecycle host.
         r.requires({ features: ["tenant-lifecycle"] });
-        // 5 fine-grained domain-events (Payload-Schemas: events.ts).
         // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
         // "displayName" stays plaintext (often the mailbox owner's real name for
         // personal accounts); encrypting it would break the entity-projection read
         // path that carries it as `personal: false`.
+        // v2: lastError, trustedAuthservId. Defaults are shared references across upcast events, so none of them is mutated.
+        const mailAccountMigrations = [
+            {
+                fromVersion: 1,
+                toVersion: 2,
+                transform: { default: { lastError: null, trustedAuthservId: null } },
+            },
+        ];
         r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
             piiFields: "none",
+            version: 2,
+            migrations: mailAccountMigrations,
         });
         r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, {
             piiFields: "none",
+            version: 2,
+            migrations: mailAccountMigrations,
         });
         r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
             piiFields: "none",
+            version: 2,
+            migrations: mailAccountMigrations,
         });
+        // v1 mails carry the snippet only: bodyText "" and contentState "snippet" let the content
+        // refetch find them. v3 adds the reason a message has no content.
         r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, {
             piiFields: "none",
+            version: 3,
+            migrations: [
+                {
+                    fromVersion: 1,
+                    toVersion: 2,
+                    transform: {
+                        default: {
+                            bodyText: "",
+                            bodyTextTruncated: false,
+                            attachmentFileIds: [],
+                            skippedAttachments: [],
+                            contentState: "snippet",
+                            senderAuthentication: null,
+                        },
+                    },
+                },
+                {
+                    fromVersion: 2,
+                    toVersion: 3,
+                    transform: { default: { contentUnavailableReason: null } },
+                },
+            ],
+        });
+        r.defineEvent(INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT, inboundMessageContentFetchedEventPayloadSchema, {
+            piiFields: "none",
+            version: 3,
+            migrations: [
+                {
+                    fromVersion: 1,
+                    toVersion: 2,
+                    transform: { default: { contentUnavailableReason: null } },
+                },
+                {
+                    fromVersion: 2,
+                    toVersion: 3,
+                    transform: { default: { accountId: null, ownerUserId: null } },
+                },
+            ],
         });
         r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
             piiFields: "none",
         });
-        // Inline projections — apply in the same transaction as the append.
         r.projection({
             name: "mail-account",
             source: MAIL_ACCOUNT_AGGREGATE_TYPE,
@@ -107,6 +154,7 @@ export function createInboundMailFoundationFeature() {
             entity: inboundMessageEntity,
             apply: {
                 [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
+                [INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN]: applyInboundMessageContentFetched,
             },
         });
         r.projection({
@@ -118,6 +166,7 @@ export function createInboundMailFoundationFeature() {
                 [MAIL_THREAD_UPDATED_EVENT_QN]: applyMailThreadUpdated,
             },
         });
+        registerMailAccountWakeConsumer(r);
         // Plugin extension point — providers register via
         // r.useExtension("inboundMailProvider", "<key>", plugin).
         r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
@@ -135,20 +184,32 @@ export function createInboundMailFoundationFeature() {
         r.storeTable(seenMessageTable, {
             reason: "read_side.mail_seen_messages_direct_write",
         });
-        // Write-Handler:
-        //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
-        //   - connect/update/disconnect-account: Lifecycle
+        r.storeTable(quarantineTable, {
+            reason: "read_side.mail_quarantine_direct_write",
+        });
+        r.storeTable(ingestFailureTable, {
+            reason: "read_side.mail_ingest_failures_direct_write",
+        });
+        // ingest-message is programmatic (supervisor/poll, SystemAdmin); the rest is 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);
-        // Declarative mailbox admin: list (rename, disconnect) and rename form.
-        // The app places `mailAccountListScreen` via r.nav in its settings area.
-        r.screen(mailAccountListScreen);
-        r.screen(mailAccountEditScreen);
+        r.writeHandler(createConnectAccountHandler(roles));
+        r.writeHandler(createUpdateAccountHandler(roles));
+        r.writeHandler(createDisconnectAccountHandler(roles));
+        r.writeHandler(createReactivateAccountHandler(roles));
+        r.writeHandler(createSetTrustedAuthservIdHandler(roles));
+        r.writeHandler(createAcknowledgeQuarantineHandler(roles));
+        r.writeHandler(createRetryQuarantinedMessageHandler(roles));
+        r.writeHandler(attachMessageContentHandler);
+        r.writeHandler(markCredentialStoredHandler);
+        r.queryHandler(createListAccountsQuery(roles));
+        r.queryHandler(createListMessagesQuery(roles));
+        r.queryHandler(createListQuarantineQuery(roles));
+        r.queryHandler(createMessageContentQuery(roles));
+        r.queryHandler(createMessageDetailQuery(roles));
+        // The app places the mailbox lists via r.nav (admins in settings, users next to their connect flow).
+        for (const screen of createMailAccountScreens(roles))
+            r.screen(screen);
+        r.screen(createMailQuarantineScreen(roles));
         r.translations({ keys: INBOUND_MAIL_FOUNDATION_I18N });
         registerMailboxProbe(r);
         // Entity-specific GDPR destroy hooks — the gdpr-storage boot validator
@@ -165,52 +226,7 @@ export function createInboundMailFoundationFeature() {
             destroy: mailThreadTenantDestroyHook,
             escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
         });
-        // Data-Retention — perTenant fan-out (one run per tenant, like
-        // data-retention:retention-cleanup): runInboundMailRetention's raw query
-        // helpers need the unfiltered runner, so the handler declares escapeHatch
-        // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
-        // + the bodies grow unbounded (GDPR Art. 5).
-        const INBOUND_MAIL_RETENTION_REASON = "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
-        r.job({
-            name: "inbound-mail-retention",
-            trigger: { cron: "0 3 * * *" },
-            perTenant: true,
-            concurrency: "skip",
-            escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
-            handler: async (_payload, ctx) => {
-                if (!ctx.registry) {
-                    throw new Error("inbound-mail-retention: ctx.registry required (JobContext incomplete)");
-                }
-                const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
-                if (tenantId === undefined) {
-                    // skip: cron fired without a perTenant fan-out tenant — nothing scoped
-                    return;
-                }
-                const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-                const retentionDb = ctx.db.unsafeRaw(); // @cast-boundary db-operator — jobs never run inside a DbTx
-                // Body objects are stored in file-foundation. The provider is lazy and memoized —
-                // ingest currently writes no bodyRef (the storeBody hook is not wired),
-                // so the provider is never built. Once storeBody is wired, retention
-                // also cleans up the bodies.
-                let providerPromise = null;
-                const deleteBodyObject = async (bodyRef) => {
-                    if (!providerPromise) {
-                        providerPromise = createFileProviderForTenant({ config: ctx.config, registry: ctx.registry, secrets: ctx.services.secrets }, tenantId);
-                    }
-                    const provider = await providerPromise;
-                    await provider.delete(bodyRef);
-                };
-                const report = await runInboundMailRetention({
-                    db: retentionDb,
-                    tenantId,
-                    now: T.Now.instant(),
-                    deleteBodyObject,
-                });
-                if (report.bodyObjectErrors > 0) {
-                    // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
-                    console.warn(`[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`);
-                }
-            },
-        });
-    }, { dedupeOptions: {} });
+        registerInboundMailRetentionJob(r);
+        return { roles };
+    }, { dedupeOptions: roleDedupeOptions(roles) });
 }

package/dist/inbound-mail-foundation/file-storage-failure.d.ts

@@ -0,0 +1,8 @@
+import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
+export declare const FILE_STORAGE_WRITE_FAILED_CODE = "file_storage_write_failed";
+export declare class FileStorageWriteFailedError extends KumikoError {
+    readonly code = "file_storage_write_failed";
+    readonly httpStatus = 503;
+    constructor(cause?: Error);
+}
+export declare function isFileStorageWriteFailure(error: unknown): boolean;

package/dist/inbound-mail-foundation/file-storage-failure.js

@@ -0,0 +1,19 @@
+import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+export const FILE_STORAGE_WRITE_FAILED_CODE = "file_storage_write_failed";
+// Own code on purpose: the supervisor treats validation/unprocessable as a poison mail and
+// quarantines it, but a storage outage says nothing about the mail.
+export class FileStorageWriteFailedError extends KumikoError {
+    code = FILE_STORAGE_WRITE_FAILED_CODE;
+    httpStatus = 503;
+    constructor(cause) {
+        super({
+            message: "inbound mail content could not be written to file storage",
+            i18nKey: "errors.internal",
+            ...(cause && { cause }),
+        });
+    }
+}
+export function isFileStorageWriteFailure(error) {
+    return errorCodeOf(error) === FILE_STORAGE_WRITE_FAILED_CODE;
+}

package/dist/inbound-mail-foundation/handlers/account-address.d.ts

@@ -0,0 +1,16 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+export type AddressMatch = {
+    readonly id: string;
+    readonly provider: string;
+    readonly authMethod: string;
+    readonly ownerUserId: string | null;
+    readonly status: string;
+};
+export declare function normalizeMailAddress(address: string): string;
+export declare function findMailboxByAddress(ctx: Pick<HandlerContext, "db">, tenantId: string, address: string): Promise<AddressMatch | undefined>;
+export type ConnectConflict = "already_connected" | "address_disconnected" | "reopen_in_place";
+export declare function connectConflictOf(existing: AddressMatch, wanted: {
+    readonly authMethod: string;
+    readonly provider: string;
+    readonly ownerUserId: string | null;
+}): ConnectConflict;

package/dist/inbound-mail-foundation/handlers/account-address.js

@@ -0,0 +1,51 @@
+// Address lookup across the tenant's mailboxes. Addresses are ciphertext in the projection, so the
+// comparison happens in memory after decrypting (a tenant has a handful of mailboxes).
+import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { InboundMailAccountStatuses, InboundMailAuthMethods } from "../constants.js";
+import { MAIL_ACCOUNT_PII_FIELDS } from "../entities.js";
+import { mailAccountsProjectionTable } from "../projection.js";
+export function normalizeMailAddress(address) {
+    return address.trim().toLowerCase();
+}
+function textOf(value) {
+    return typeof value === "string" ? value : "";
+}
+// A live mailbox wins over a disconnected one: connecting next to a live mailbox is always a duplicate.
+export async function findMailboxByAddress(ctx, tenantId, address) {
+    const wanted = normalizeMailAddress(address);
+    const rows = await ctx.db.selectMany(mailAccountsProjectionTable, { tenantId });
+    const piiKms = configuredPiiSubjectKms();
+    const matches = [];
+    for (const row of rows) {
+        const readable = piiKms
+            ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+                requestId: `inbound-mail-foundation:connect-account:${tenantId}`,
+            })
+            : row;
+        if (normalizeMailAddress(textOf(readable["address"])) !== wanted)
+            continue;
+        matches.push({
+            id: textOf(row["id"]),
+            provider: textOf(row["provider"]),
+            authMethod: textOf(row["authMethod"]),
+            ownerUserId: typeof row["ownerUserId"] === "string" ? row["ownerUserId"] : null,
+            status: textOf(row["status"]),
+        });
+    }
+    return matches.find((m) => m.status !== InboundMailAccountStatuses.disconnected) ?? matches[0];
+}
+// A disconnected or sign-in-failed OAuth mailbox of the same provider and owner is reopened (the
+// callback writes the new token into the same slot); everything else must not silently create a second stream for one address.
+export function connectConflictOf(existing, wanted) {
+    const disconnected = existing.status === InboundMailAccountStatuses.disconnected;
+    // A sign-in error of an OAuth mailbox is healed by signing in again, so it reopens like a disconnect.
+    const signInFailed = existing.status === InboundMailAccountStatuses.authError;
+    if (!disconnected && !signInFailed)
+        return "already_connected";
+    const bothOauth = wanted.authMethod === InboundMailAuthMethods.oauth &&
+        existing.authMethod === InboundMailAuthMethods.oauth &&
+        existing.provider === wanted.provider;
+    if (!bothOauth)
+        return disconnected ? "address_disconnected" : "already_connected";
+    return existing.ownerUserId === wanted.ownerUserId ? "reopen_in_place" : "already_connected";
+}