@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message-prepare.ts

@@ -0,0 +1,177 @@
+// Pre-transaction half of the content storage: original and attachments are written while no
+// transaction holds a connection, so a slow or failing file store never pins the database. The
+// handler transaction only creates the fileRef rows (finalizePreparedContent).
+
+import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  createFileRefFromUploadedBytes,
+  type UploadedFileBytes,
+  uploadFileBytesBeforeTransaction,
+} from "@cosmicdrift/kumiko-framework/files";
+import type {
+  BeforeTransactionContext,
+  BeforeTransactionResult,
+  ReservationRelease,
+} from "@cosmicdrift/kumiko-types/handlers";
+import { inboundMessageAggregateId } from "../aggregate-id.ts";
+import { seenMessageTable } from "../entities.ts";
+import { FileStorageWriteFailedError } from "../file-storage-failure.ts";
+import { INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT } from "../normalize-inbound-message.ts";
+import type { SkippedInboundAttachment } from "../types.ts";
+import type { IngestMessagePayload } from "./ingest-message-schema.ts";
+import {
+  contentWithoutFileStorage,
+  type InboundContentInput,
+  inboundAttachmentMaxSize,
+  inboundAttachmentTarget,
+  inboundMessageBodyKey,
+  originalOf,
+  type StoredInboundContent,
+} from "./message-content.ts";
+
+export type PreparedInboundContent = {
+  readonly bodyRef: string;
+  readonly uploads: readonly UploadedFileBytes[];
+  readonly skippedAttachments: readonly SkippedInboundAttachment[];
+  readonly contentStorage: StoredInboundContent["contentStorage"];
+};
+
+export type PreparedIngest =
+  | { readonly duplicate: true }
+  | { readonly duplicate: false; readonly content: PreparedInboundContent };
+
+type PrepareContext = Pick<BeforeTransactionContext, "db" | "services" | "registry" | "user">;
+
+function storageFailure(cause: unknown) {
+  return writeFailure(new FileStorageWriteFailedError(cause instanceof Error ? cause : undefined));
+}
+
+async function releaseAll(releases: readonly ReservationRelease[]): Promise<void> {
+  for (const release of releases) await release();
+}
+
+// The deterministic original key is never released: a concurrent winner owns it and writing it
+// again is idempotent.
+export async function prepareInboundContent(
+  ctx: PrepareContext,
+  input: InboundContentInput,
+): Promise<BeforeTransactionResult<PreparedInboundContent>> {
+  const { files } = ctx.services;
+  if (!files) {
+    const unavailable = contentWithoutFileStorage(input);
+    return {
+      isSuccess: true,
+      data: {
+        bodyRef: unavailable.bodyRef,
+        uploads: [],
+        skippedAttachments: unavailable.skippedAttachments,
+        contentStorage: unavailable.contentStorage,
+      },
+    };
+  }
+
+  let bodyRef = input.bodyRef;
+  const original = originalOf(input);
+  if (bodyRef === "" && original) {
+    bodyRef = inboundMessageBodyKey(
+      ctx.user.tenantId,
+      input.accountId,
+      input.messageAggId,
+      original.extension,
+    );
+    try {
+      await files.ref(bodyRef).write(original.data, original.mimeType);
+    } catch (err) {
+      return storageFailure(err);
+    }
+  }
+
+  const uploads: UploadedFileBytes[] = [];
+  const releases: ReservationRelease[] = [];
+  const skipped = [...(input.skippedAttachments ?? [])];
+  const maxSize = inboundAttachmentMaxSize(ctx.registry);
+  for (const attachment of input.attachments ?? []) {
+    let uploaded: Awaited<ReturnType<typeof uploadFileBytesBeforeTransaction>>;
+    try {
+      uploaded = await uploadFileBytesBeforeTransaction(ctx, {
+        fileName: attachment.fileName,
+        mimeType: attachment.mimeType,
+        data: attachment.data,
+        attachTo: inboundAttachmentTarget(input.messageAggId),
+        maxSize,
+      });
+    } catch (err) {
+      await releaseAll(releases);
+      return storageFailure(err);
+    }
+    // A rejected attachment (size, MIME) is a property of the mail, not an outage.
+    if (!uploaded.isSuccess) {
+      skipped.push({
+        mimeType: attachment.mimeType,
+        size: attachment.data.byteLength,
+        reason: "rejected",
+      });
+      continue;
+    }
+    uploads.push(uploaded.data);
+    if (uploaded.release) releases.push(uploaded.release);
+  }
+  return {
+    isSuccess: true,
+    data: {
+      bodyRef,
+      uploads,
+      skippedAttachments: skipped.slice(0, INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT),
+      contentStorage: "stored",
+    },
+    release: () => releaseAll(releases),
+  };
+}
+
+/** Transaction half: creates the fileRef rows for the bytes the prepare phase wrote. */
+export async function finalizePreparedContent(
+  ctx: Parameters<typeof createFileRefFromUploadedBytes>[0],
+  prepared: PreparedInboundContent,
+): Promise<StoredInboundContent> {
+  const attachmentFileIds: string[] = [];
+  const skipped = [...prepared.skippedAttachments];
+  for (const upload of prepared.uploads) {
+    const created = await createFileRefFromUploadedBytes(ctx, upload);
+    if (created.isSuccess) attachmentFileIds.push(created.data.id);
+    else skipped.push({ mimeType: upload.mimeType, size: upload.size, reason: "rejected" });
+  }
+  return {
+    bodyRef: prepared.bodyRef,
+    attachmentFileIds,
+    skippedAttachments: skipped.slice(0, INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT),
+    contentStorage: prepared.contentStorage,
+  };
+}
+
+/** Dedup read first: a duplicate uploads nothing. The in-transaction dedup stays the correctness anchor. */
+export async function prepareIngestMessage(
+  event: { readonly payload: IngestMessagePayload },
+  ctx: PrepareContext,
+): Promise<BeforeTransactionResult<PreparedIngest>> {
+  const { payload } = event;
+  const seen = await ctx.db.selectMany(seenMessageTable, {
+    accountId: payload.accountId,
+    providerMessageId: payload.providerMessageId,
+  });
+  if (seen.length > 0) return { isSuccess: true, data: { duplicate: true } };
+  const prepared = await prepareInboundContent(ctx, {
+    accountId: payload.accountId,
+    messageAggId: inboundMessageAggregateId(payload.accountId, payload.providerMessageId),
+    bodyRef: payload.bodyRef,
+    rawMime: payload.rawMime,
+    bodyHtml: payload.bodyHtml,
+    attachments: payload.attachments,
+    skippedAttachments: payload.skippedAttachments,
+  });
+  if (!prepared.isSuccess) return prepared;
+  return {
+    isSuccess: true,
+    data: { duplicate: false, content: prepared.data },
+    ...(prepared.release && { release: prepared.release }),
+  };
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message-schema.ts

@@ -0,0 +1,42 @@
+import * as z from "zod";
+import { senderAuthenticationFieldSchema } from "../sender-auth.ts";
+import { inboundContentPayloadShape } from "./message-content.ts";
+
+// =============================================================================
+// Input schema — the normalized provider output (RawInboundMessage,
+// types.ts) plus the envelope (accountId/providerName/providerCursor). The
+// original and attachments ride in-process as bytes and are persisted to file
+// storage here; the event itself stays blob-free (references only).
+// =============================================================================
+
+export const ingestMessageSchema = z.object({
+  accountId: z.uuid(),
+  /** Scope inherited from the account — the supervisor knows the
+   *  MailAccountRecord and passes ownerUserId through. */
+  ownerUserId: z.string().max(36).nullable(),
+  providerName: z.string().min(1).max(50),
+  /** Provider-native Message-ID — idempotency anchor with accountId. */
+  providerMessageId: z.string().min(1).max(500),
+  /** RFC-5322 Message-ID without <>; null → deterministic fallback. */
+  messageIdHeader: z.string().min(1).max(500).nullable(),
+  providerThreadId: z.string().min(1).max(500).nullable(),
+  /** References/In-Reply-To chain, oldest first. */
+  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),
+  /** From the app's storeBody hook; empty lets the handler store the original itself. */
+  bodyRef: z.string().max(500),
+  scope: z.string().min(1).max(200),
+  /** Cursor snapshot at ingest time — used for debugging/replay and stored in
+   *  metadata.headers, never in the payload. */
+  providerCursor: z.string().max(2000),
+  senderAuthentication: senderAuthenticationFieldSchema.optional(),
+  /** Set when the message is imported from its headers only because it sits in quarantine. */
+  contentUnavailableReason: z.literal("quarantined").optional(),
+  ...inboundContentPayloadShape,
+});
+export type IngestMessagePayload = z.infer<typeof ingestMessageSchema>;

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

@@ -2,11 +2,14 @@
 // (watch callback + fetchSince sync). Accepts a normalized
 // RawInboundMessage and performs atomically in ONE TX:
 //
+//   0. Per-message advisory lock, so a watch/poll race cannot store the same
+//      content twice (orphaned FileRefs) before the dedup checks run.
 //   1. Idempotency check (cheap: store_mail_seen_messages; defense in
 //      depth: stream existence check on the deterministic aggregateId).
 //   2. threadKey normalization (provider thread ID preferred, otherwise
 //      References chain root, otherwise Message-ID = single-message thread).
-//   3. PII encryption (from/to/cc/subject/snippet) BEFORE the append —
+//   3. Content storage (original + attachments, only after dedup) and PII
+//      encryption (from/to/cc/subject/snippet/bodyText) BEFORE the append —
 //      both the event log AND projection contain ciphertext.
 //   4. inbound-message-received append (inline projection writes
 //      read_inbound_messages in the same TX). Savepoint-scoped
@@ -24,90 +27,43 @@ import {
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import { acquireNamespacedAdvisoryLock, countWhere } from "@cosmicdrift/kumiko-framework/db";
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import * as z from "zod";
 import { inboundMessageAggregateId, mailThreadAggregateId } from "../aggregate-id.ts";
-import {
-  INBOUND_MESSAGE_PII_FIELDS,
-  inboundMessageEntity,
-  MAIL_THREAD_PII_FIELDS,
-  mailThreadEntity,
-  seenMessageTable,
-} from "../entities.ts";
+import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, seenMessageTable } from "../entities.ts";
 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.ts";
-import { inboundMessagesProjectionTable } from "../projection.ts";
-
-// =============================================================================
-// Input schema — the normalized provider output (RawInboundMessage,
-// types.ts) plus the envelope (accountId/providerName/providerCursor). rawMime
-// is intentionally excluded: the caller persists the body to
-// file-foundation BEFORE the ingest call and passes only bodyRef — the
-// handler payload remains blob-free (event-store discipline).
-// =============================================================================
-
-export const ingestMessageSchema = z.object({
-  accountId: z.uuid(),
-  /** Scope inherited from the account — the supervisor knows the
-   *  MailAccountRecord and passes ownerUserId through. */
-  ownerUserId: z.string().max(36).nullable(),
-  providerName: z.string().min(1).max(50),
-  /** Provider-native Message-ID — idempotency anchor with accountId. */
-  providerMessageId: z.string().min(1).max(500),
-  /** RFC-5322 Message-ID without <>; null → deterministic fallback. */
-  messageIdHeader: z.string().min(1).max(500).nullable(),
-  providerThreadId: z.string().min(1).max(500).nullable(),
-  /** References/In-Reply-To chain, oldest first. */
-  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 at ingest time — used for debugging/replay and stored in
-   *  metadata.headers, never in the payload. */
-  providerCursor: z.string().max(2000),
-});
-type IngestMessagePayload = z.infer<typeof ingestMessageSchema>;
-
-/**
- * Normalizes threadKey:
- *   1. Use the provider thread ID when present — prefix it with the provider
- *      so IMAP References keys and Graph conversationIds never collide.
- *   2. Otherwise use the root of the References chain (the oldest Message-ID,
- *      which is the thread anchor shared by all replies).
- *   3. Otherwise use the own Message-ID → single-message thread; a later
- *      reply carries it as the References root and joins the same 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);
-}
+import {
+  finalizePreparedContent,
+  type PreparedIngest,
+  prepareIngestMessage,
+} from "./ingest-message-prepare.ts";
+import { ingestMessageSchema } from "./ingest-message-schema.ts";
+import {
+  contentStateOf,
+  MESSAGE_LOCK_NAMESPACE,
+  storeInboundMessageContent,
+} from "./message-content.ts";
+import { appendThreadRollup, buildThreadKey } from "./thread-rollup.ts";
 
-const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
-// pg_advisory_xact_lock namespace (int4) for the step-5 thread-rollup lock
-// — 'inbm' as ASCII, keeps it disjoint from the framework's other fixed
-// single-int advisory-lock keys (schema bootstrap, es-ops boot).
-const THREAD_ROLLUP_LOCK_NAMESPACE = 0x696e626d;
 const THREAD_ROLLUP_ADVISORY_LOCK_REASON =
   "takes the per-thread advisory lock and counts the caller tenant's thread messages; TenantDb has no lock/count API";
-export const ingestMessageHandler: WriteHandlerDef = {
+type IngestMessageData =
+  | { readonly duplicate: true; readonly inboundMessageAggregateId: string }
+  | {
+      readonly duplicate: false;
+      readonly inboundMessageAggregateId: string;
+      readonly threadAggregateId: string;
+      readonly threadKey: string;
+      readonly contentStorage: "stored" | "unavailable";
+    };
+
+export const ingestMessageHandler = defineWriteHandler({
   name: "ingest-message",
   schema: ingestMessageSchema,
   access: { roles: ["SystemAdmin"] },
@@ -116,12 +72,16 @@ export const ingestMessageHandler: WriteHandlerDef = {
     grants: ["unsafeRaw"],
     reason: THREAD_ROLLUP_ADVISORY_LOCK_REASON,
   },
-  handler: async (event, ctx) => {
-    // @cast-boundary engine-payload — dispatcher-zod-validated payload
-    const payload = event.payload as IngestMessagePayload;
+  // Nested (an app handler dispatching ingest-message) there is no phase; the handler then stores in its own transaction.
+  beforeTransactionWhenNested: "skip",
+  beforeTransaction: prepareIngestMessage,
+  handler: async (event, ctx): Promise<WriteResult<IngestMessageData>> => {
+    const { payload } = event;
     const tenantId = event.user.tenantId;
     const messageAggId = inboundMessageAggregateId(payload.accountId, payload.providerMessageId);
 
+    await ctx.db.advisoryXactLock(MESSAGE_LOCK_NAMESPACE, messageAggId);
+
     // ---------------------------------------------------------------
     // 1. Idempotency. Use the deduplication anchor row first because it is
     //    cheap. The stream check afterward provides defense in depth if
@@ -168,9 +128,26 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    (primitives only, upcaster-safe). If no KMS is configured, pass
     //    through plaintext (engine-off behavior).
     // ---------------------------------------------------------------
+    const prepared: PreparedIngest | undefined = event.prepared;
+    const content =
+      prepared?.duplicate === false
+        ? await finalizePreparedContent(ctx, prepared.content)
+        : await storeInboundMessageContent(ctx, {
+            accountId: payload.accountId,
+            messageAggId,
+            bodyRef: payload.bodyRef,
+            rawMime: payload.rawMime,
+            bodyHtml: payload.bodyHtml,
+            attachments: payload.attachments,
+            skippedAttachments: payload.skippedAttachments,
+          });
+    const contentUnavailableReason =
+      payload.contentUnavailableReason ??
+      (content.contentStorage === "unavailable" ? ("no_file_storage" as const) : null);
     const piiKms = configuredPiiSubjectKms();
     const messagePlainPii = {
       tenantId,
+      bodyText: payload.bodyText,
       from: payload.from,
       to: JSON.stringify(payload.to),
       cc: JSON.stringify(payload.cc),
@@ -203,8 +180,22 @@ export const ingestMessageHandler: WriteHandlerDef = {
       subject: encryptedMessageFields.subject,
       snippet: encryptedMessageFields.snippet,
       receivedAtIso: payload.receivedAtIso,
-      bodyRef: payload.bodyRef,
+      bodyRef: content.bodyRef,
       scope: payload.scope,
+      senderAuthentication: payload.senderAuthentication ?? null,
+      bodyText: encryptedMessageFields.bodyText,
+      bodyTextTruncated: payload.bodyTextTruncated,
+      attachmentFileIds: content.attachmentFileIds,
+      skippedAttachments: content.skippedAttachments,
+      contentState:
+        payload.contentUnavailableReason !== undefined
+          ? "unavailable"
+          : contentStateOf({
+              bodyText: payload.bodyText,
+              hasOriginal: payload.rawMime !== undefined || payload.bodyHtml !== undefined,
+              contentStorage: content.contentStorage,
+            }),
+      contentUnavailableReason,
     };
     const messageHeaders: InboundMessageEventHeaders = {
       providerMessageId: payload.providerMessageId,
@@ -230,88 +221,15 @@ export const ingestMessageHandler: WriteHandlerDef = {
       };
     }
 
-    // ---------------------------------------------------------------
-    // 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
-    //    ctx.events.tryAppend 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 is a live COUNT, not previousCount+1, so two
-    //    concurrent ingests on the same thread (Watch-Push vs.
-    //    Poll-Reconciliation overlap, or two different messages of the
-    //    same thread arriving at once) converge on the true count.
-    //    acquireNamespacedAdvisoryLock below serializes this whole
-    //    countWhere+append section per threadAggId — transaction-scoped,
-    //    so it survives events.tryAppend's inner SAVEPOINT and releases at
-    //    the enclosing TX's commit/rollback. Without it, a concurrent
-    //    commit landing between countWhere and events.tryAppend's own fresh
-    //    version-read makes the append succeed with a stale count instead
-    //    of a VersionConflictError, so the retry loop below never sees it
-    //    as a conflict to retry (the original gap). 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.
-    // ---------------------------------------------------------------
-    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,
-          },
-          { tenantId, entityName: MAIL_THREAD_AGGREGATE_TYPE },
-        )
-      : threadPlainPii;
-
-    const threadRollupRunner = ctx.db.unsafeRaw();
-    await acquireNamespacedAdvisoryLock(
-      threadRollupRunner,
-      THREAD_ROLLUP_LOCK_NAMESPACE,
+    await appendThreadRollup(ctx, {
+      tenantId,
       threadAggId,
-    );
-
-    let threadAppendOk = false;
-    for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
-      const threadEvents = await ctx.events.load(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(threadRollupRunner, inboundMessagesProjectionTable, {
-        tenantId,
-        threadKey,
-      });
-
-      const threadEventPayload: MailThreadEventPayload = {
-        threadKey,
-        subject: encryptedThreadFields.subject,
-        lastMessageAtIso: newLastAt,
-        messageCount,
-      };
-      const threadAppend = await ctx.events.tryAppend({
-        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.`,
-      });
-    }
+      threadKey,
+      subject: payload.subject,
+      receivedAtIso: payload.receivedAtIso,
+      headers: messageHeaders,
+      piiKms,
+    });
 
     // ---------------------------------------------------------------
     // 6. Deduplication anchor. It runs in the same TX as the appends, so
@@ -331,7 +249,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
         inboundMessageAggregateId: messageAggId,
         threadAggregateId: threadAggId,
         threadKey,
+        contentStorage: content.contentStorage,
       },
     };
   },
-};
+});

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

@@ -3,8 +3,8 @@
 // billing-foundation list-subscriptions pattern.
 //
 // **Scope visibility:** authorized users can see shared mailboxes
-// (ownerUserId=null); personal mailboxes are visible only to their owner,
-// TenantAdmin, or SystemAdmin for compliance access. Filtering runs in memory
+// (ownerUserId=null); personal mailboxes are listed (metadata only) for their owner and the
+// admin roles, but only the owner sees their quarantine. Filtering runs in memory
 // after the tenant-scoped select because a tenant has only a single- to
 // double-digit number of connected mailboxes.
 import {
@@ -13,39 +13,102 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import { MAX_LIST_LIMIT, type QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import {
+  IMAP_PROVIDER_KEY,
+  InboundMailAccountStatuses,
+  InboundMailAuthMethods,
+  type MailAccountReactivationPath,
+  MailAccountReactivationPaths,
+} from "../constants.ts";
 import { MAIL_ACCOUNT_PII_FIELDS } from "../entities.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
 import { mailAccountsProjectionTable } from "../projection.ts";
-import { isVisibleToCaller } from "./scope-visibility.ts";
+import { quarantineTable } from "../quarantine-entities.ts";
+import {
+  isAccountListableBy,
+  mayManageQuarantine,
+  mayReactivateMailbox,
+} from "./scope-visibility.ts";
+
+const REACTIVATABLE_STATUSES: ReadonlySet<unknown> = new Set([
+  InboundMailAccountStatuses.disconnected,
+  InboundMailAccountStatuses.authError,
+]);
+
+// Null where no way back exists for this caller, so no row action leads into a refusal.
+function reactivationPathOf(
+  row: Readonly<Record<string, unknown>>,
+  user: { readonly id: string; readonly roles: readonly string[] },
+  adminRoles: readonly string[],
+): MailAccountReactivationPath | null {
+  if (!REACTIVATABLE_STATUSES.has(row["status"])) return null;
+  if (!mayReactivateMailbox(row["ownerUserId"], user, adminRoles)) return null;
+  if (row["authMethod"] === InboundMailAuthMethods.oauth)
+    return MailAccountReactivationPaths.oauthFlow;
+  const isPasswordImap =
+    row["provider"] === IMAP_PROVIDER_KEY && row["authMethod"] === InboundMailAuthMethods.password;
+  return isPasswordImap ? MailAccountReactivationPaths.passwordForm : null;
+}
 
 // The projectionList screen always sends `limit`; unknown keys stay rejected.
 const listAccountsSchema = z
   .object({ limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT) })
   .strict();
 
-export const listAccountsQuery: QueryHandlerDef = {
-  name: "account:list",
-  schema: listAccountsSchema,
-  access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
-  description:
-    "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers; use it for the mail connect and settings views.",
-  handler: async (query, ctx) => {
-    const { limit } = listAccountsSchema.parse(query.payload);
-    const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
-      tenantId: ctx.user.tenantId,
-    });
-    const rows = allRows
-      .filter((row) => isVisibleToCaller(row, ctx.user))
-      .sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))
-      .slice(0, limit);
-    const piiKms = configuredPiiSubjectKms();
-    if (!piiKms) return { rows };
-    const decryptedRows = await Promise.all(
-      rows.map((row) =>
-        decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-          requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
-        }),
-      ),
-    );
-    return { rows: decryptedRows };
-  },
-};
+export function createListAccountsQuery({
+  memberRoles,
+  adminRoles,
+}: InboundMailRoles): QueryHandlerDef {
+  return {
+    name: "account:list",
+    schema: listAccountsSchema,
+    access: { roles: [...memberRoles] },
+    description:
+      "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers and the quarantine of personal mailboxes the caller does not own; use it for the mail connect and settings views.",
+    handler: async (query, ctx) => {
+      const { limit } = listAccountsSchema.parse(query.payload);
+      const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
+        tenantId: ctx.user.tenantId,
+      });
+      const rows = allRows
+        .filter((row) => isAccountListableBy(row, ctx.user, adminRoles))
+        .sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))
+        .slice(0, limit);
+      // One grouped count for all mailboxes instead of a query per row.
+      const openQuarantine = await ctx.db.aggregate(
+        quarantineTable,
+        { measure: { fn: "count" }, groupBy: [{ field: "accountId" }] },
+        { acknowledgedAt: null },
+      );
+      const quarantinedCountOf = new Map(
+        openQuarantine.map((group) => [String(group.keys[0]), group.value ?? 0]),
+      );
+      // The screen's row condition cannot compare a count or combine fields, so it gets booleans.
+      const withQuarantine = (row: Record<string, unknown>) => {
+        const owner = row["ownerUserId"];
+        const mayManage = mayManageQuarantine(
+          typeof owner === "string" && owner !== "" ? owner : null,
+          ctx.user,
+          adminRoles,
+        );
+        const quarantinedCount = mayManage ? (quarantinedCountOf.get(String(row["id"])) ?? 0) : 0;
+        return {
+          ...row,
+          quarantinedCount,
+          hasOpenQuarantine: quarantinedCount > 0,
+          reactivateVia: reactivationPathOf(row, ctx.user, adminRoles),
+        };
+      };
+      const piiKms = configuredPiiSubjectKms();
+      if (!piiKms) return { rows: rows.map(withQuarantine) };
+      const decryptedRows = await Promise.all(
+        rows.map((row) =>
+          decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+            requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
+          }),
+        ),
+      );
+      return { rows: decryptedRows.map(withQuarantine) };
+    },
+  };
+}