@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.159.1

package/src/auth-mfa/web/__tests__/mfa-verify-screen.test.tsx

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, type RenderResult, render, screen, waitFor } from "@testing-library/react";
+import type { ReactElement } from "react";
+import { makeSessionApi } from "../../../auth-email-password/web/__tests__/test-utils";
+import { SessionContext } from "../../../auth-email-password/web/session";
+import { defaultTranslations } from "../i18n";
+import { MfaVerifyScreen } from "../mfa-verify-screen";
+
+function renderScreen(ui: ReactElement, session = makeSessionApi()): RenderResult {
+  return render(
+    <PrimitivesProvider value={defaultPrimitives}>
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "de" })}
+        fallbackBundles={[defaultTranslations]}
+      >
+        <SessionContext.Provider value={session}>{ui}</SessionContext.Provider>
+      </LocaleProvider>
+    </PrimitivesProvider>,
+  );
+}
+
+beforeEach(() => {
+  globalThis.fetch = mock(
+    async () => new Response(null, { status: 200 }),
+  ) as unknown as typeof fetch;
+});
+afterEach(() => {});
+
+describe("MfaVerifyScreen", () => {
+  test("rendert Titel + Code-Feld + Submit-Button (de)", () => {
+    void renderScreen(<MfaVerifyScreen challengeToken="challenge-1" />);
+    expect(screen.getByText("Zwei-Faktor-Bestätigung")).toBeTruthy();
+    expect(screen.getByLabelText(/^Code/)).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Bestätigen" })).toBeTruthy();
+  });
+
+  test("richtiger Code → ruft session.refresh() + onSuccess()", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            isSuccess: true,
+            token: "t",
+            user: { id: "u1", tenantId: "t1", roles: [] },
+          }),
+          { status: 200 },
+        ),
+    ) as unknown as typeof fetch;
+    const session = makeSessionApi();
+    const onSuccess = mock(() => {});
+    void renderScreen(
+      <MfaVerifyScreen challengeToken="challenge-1" onSuccess={onSuccess} />,
+      session,
+    );
+
+    fireEvent.change(screen.getByLabelText(/^Code/), { target: { value: "123456" } });
+    fireEvent.click(screen.getByRole("button", { name: "Bestätigen" }));
+
+    await waitFor(() => {
+      expect(session.refresh).toHaveBeenCalled();
+      expect(onSuccess).toHaveBeenCalled();
+    });
+  });
+
+  test("falscher Code (invalid_totp_code) → Banner mit übersetztem Text", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(JSON.stringify({ isSuccess: false, error: "invalid_totp_code" }), {
+          status: 200,
+        }),
+    ) as unknown as typeof fetch;
+    void renderScreen(<MfaVerifyScreen challengeToken="challenge-1" />);
+
+    fireEvent.change(screen.getByLabelText(/^Code/), { target: { value: "000000" } });
+    fireEvent.click(screen.getByRole("button", { name: "Bestätigen" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Ungültiger Code. Bitte erneut versuchen.")).toBeTruthy();
+    });
+  });
+
+  test("onCancel gesetzt → 'Zurück zum Login'-Button vorhanden, klick ruft onCancel", () => {
+    const onCancel = mock(() => {});
+    void renderScreen(<MfaVerifyScreen challengeToken="challenge-1" onCancel={onCancel} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Zurück zum Login" }));
+    expect(onCancel).toHaveBeenCalled();
+  });
+
+  test("ohne onCancel → kein 'Zurück zum Login'-Button", () => {
+    void renderScreen(<MfaVerifyScreen challengeToken="challenge-1" />);
+    expect(screen.queryByRole("button", { name: "Zurück zum Login" })).toBeNull();
+  });
+});

package/src/billing-foundation/__tests__/subscription-provider-contract.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { SubscriptionProviderPlugin } from "../types";
+
+export type SubscriptionProviderContractFixture = {
+  readonly plugin: SubscriptionProviderPlugin;
+  readonly ctx: HandlerContext;
+  readonly checkout: Parameters<
+    NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
+  >[1];
+  // Providers without a customer-portal (e.g. Mollie) omit this — the
+  // portal-test then skips, mirroring `createPortalSession` being optional.
+  readonly portal?: Parameters<NonNullable<SubscriptionProviderPlugin["createPortalSession"]>>[1];
+  readonly cancelSubscriptionId?: string;
+  // A real, provider-signed/verifiable webhook payload for the happy path.
+  // Providers without a fixture skip the webhook-parsing test — building one
+  // needs provider-specific signing (Stripe HMAC) or a mocked API client
+  // (Mollie lazy-fetch), which the provider's own verify-webhook.test.ts
+  // already assembles.
+  readonly webhook?: {
+    readonly rawBody: string;
+    readonly headers: Record<string, string>;
+    readonly expectedTenantId: string;
+    readonly expectedTier: string;
+  };
+};
+
+export function describeSubscriptionProviderContract(
+  name: string,
+  factory: () => SubscriptionProviderContractFixture | Promise<SubscriptionProviderContractFixture>,
+): void {
+  describe(`${name} — SubscriptionProviderPlugin contract`, () => {
+    test("implements verifyAndParseWebhook", async () => {
+      const { plugin } = await factory();
+      expect(typeof plugin.verifyAndParseWebhook).toBe("function");
+    });
+
+    test("verifyAndParseWebhook parses a valid provider event into a SubscriptionEvent", async () => {
+      const { plugin, webhook } = await factory();
+      if (!webhook) return;
+      const event = await plugin.verifyAndParseWebhook(webhook.rawBody, webhook.headers);
+      expect(event).not.toBeNull();
+      expect(event?.tenantId).toBe(webhook.expectedTenantId);
+      expect(event?.tier).toBe(webhook.expectedTier);
+    });
+
+    test("createCheckoutSession returns a hosted-page url", async () => {
+      const { plugin, ctx, checkout } = await factory();
+      if (!plugin.createCheckoutSession) return;
+      const result = await plugin.createCheckoutSession(ctx, checkout);
+      expect(typeof result.url).toBe("string");
+      expect(result.url.length).toBeGreaterThan(0);
+    });
+
+    test("createPortalSession returns a hosted-page url — providers without a portal skip", async () => {
+      const { plugin, ctx, portal } = await factory();
+      if (!plugin.createPortalSession || !portal) return;
+      const result = await plugin.createPortalSession(ctx, portal);
+      expect(typeof result.url).toBe("string");
+      expect(result.url.length).toBeGreaterThan(0);
+    });
+
+    test("cancelSubscription resolves without throwing — providers without cancel-support skip", async () => {
+      const { plugin, ctx, cancelSubscriptionId } = await factory();
+      if (!plugin.cancelSubscription || !cancelSubscriptionId) return;
+      await expect(plugin.cancelSubscription(ctx, cancelSubscriptionId)).resolves.toBeUndefined();
+    });
+  });
+}

package/src/channel-email/pii-guard.ts

@@ -2,21 +2,24 @@ import { PII_CIPHERTEXT_PREFIX } from "@cosmicdrift/kumiko-framework/crypto";
 import type { EmailMessage, EmailTransport } from "./types";
 
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
-const CIPHERTEXT_RE = /kumiko-pii:v1:[^"\s<>\\]*/g;
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 
 // A PII ciphertext never belongs in an outgoing mail. A ciphertext RECIPIENT
 // is always refused (the address is garbage — better no mail than a leaked
 // blob); ciphertext in subject/body fails loud in dev and is redacted+logged
 // in prod.
 export function guardEmailMessage(message: EmailMessage): EmailMessage {
-  if (message.to.includes(PII_CIPHERTEXT_PREFIX)) {
+  if (message.to.includes(CIPHERTEXT_MARKER)) {
     throw new Error(
       "[channel-email] refusing to send: recipient address is a PII ciphertext " +
         `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`,
     );
   }
   const leaking =
-    message.subject.includes(PII_CIPHERTEXT_PREFIX) || message.html.includes(PII_CIPHERTEXT_PREFIX);
+    message.subject.includes(CIPHERTEXT_MARKER) || message.html.includes(CIPHERTEXT_MARKER);
   if (!leaking) return message;
   const detail =
     "[channel-email] mail subject/body contains a PII ciphertext " +

package/src/config/__tests__/config.integration.test.ts

@@ -1086,6 +1086,20 @@ describe("encrypted config", () => {
     const value = await configFn("integration:config:api-secret");
     expect(value).toBe("sk-super-secret-key-12345");
   });
+
+  test("reading an encrypted value with no cipher wired throws instead of leaking ciphertext", async () => {
+    const noCipherResolver = createConfigResolver({});
+    const configFn = createConfigAccessor(
+      stack.registry,
+      noCipherResolver,
+      "00000000-0000-4000-8000-000000000001",
+      systemAdmin.id,
+      db,
+    );
+    await expect(configFn("integration:config:api-secret")).rejects.toThrow(
+      /encrypted but no cipher/,
+    );
+  });
 });
 
 // --- Config lifecycle events ---

package/src/config/__tests__/pii-encrypted.integration.test.ts

@@ -11,6 +11,7 @@ import {
   configurePiiSubjectKms,
   InMemoryKmsAdapter,
   isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import {
@@ -96,7 +97,7 @@ describe("piiEncrypted config keys", () => {
     });
     expect(row).toBeDefined();
     expect(isPiiCiphertext(row?.value)).toBe(true);
-    expect(row?.value).toStartWith(`kumiko-pii:v1:tenant:${tenantAdmin.tenantId}:`);
+    expect(row?.value).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${tenantAdmin.tenantId}:`);
 
     const values = await stack.http.queryOk<
       Record<string, { value: unknown; scope: string; source: string }>
@@ -118,7 +119,7 @@ describe("piiEncrypted config keys", () => {
     });
     expect(row).toBeDefined();
     expect(isPiiCiphertext(row?.value)).toBe(true);
-    expect(row?.value).toStartWith(`kumiko-pii:v1:user:${tenantAdmin.id}:`);
+    expect(row?.value).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${tenantAdmin.id}:`);
 
     const values = await stack.http.queryOk<
       Record<string, { value: unknown; scope: string; source: string }>

package/src/config/__tests__/reencrypt-job-concurrent-write-race.integration.test.ts

@@ -136,7 +136,10 @@ const noopLog = {
 // that's the point in migrateRow right after decrypt, right before its own
 // executor.update, so the job's captured row.version is guaranteed stale by
 // the time it issues that update.
-function racyJobCtx(rowVersionAtBatchRead: number): Parameters<typeof reencryptJob>[1] {
+function racyJobCtx(
+  rowVersionAtBatchRead: number,
+  log: typeof noopLog = noopLog,
+): Parameters<typeof reencryptJob>[1] {
   let fired = false;
   const racyCipher: EnvelopeCipher = {
     decrypt: (stored, scope) => cipher.decrypt(stored, scope),
@@ -153,7 +156,7 @@ function racyJobCtx(rowVersionAtBatchRead: number): Parameters<typeof reencryptJ
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: racyCipher,
-    log: noopLog,
+    log,
   } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
 }
 
@@ -187,7 +190,21 @@ describe("config KEK-rotation job — concurrent write race (kumiko-framework#11
       }),
     );
 
-    await reencryptJob({}, racyJobCtx(seeded.version));
+    // Distinguishes "skipped" (version_conflict, row already fine) from
+    // "failed" (any other rejection) — both leave the row's end-state
+    // identical (reencrypt.job.ts:159-166), so a regression that silently
+    // turns this branch into "failed" would pass every assertion below it.
+    // The warn log at reencrypt.job.ts:171 is the only observable signature
+    // that fires on "failed" but not on "skipped" — assert it stayed silent.
+    const warnCalls: unknown[][] = [];
+    const spyLog = {
+      ...noopLog,
+      warn: (...args: unknown[]) => {
+        warnCalls.push(args);
+      },
+    };
+    await reencryptJob({}, racyJobCtx(seeded.version, spyLog));
+    expect(warnCalls).toEqual([]);
 
     // The concurrent write already lands under the current key — its
     // envelope must survive untouched; the rotation job's own update lost

package/src/config/__tests__/reencrypt-job-kek-rotation.integration.test.ts

@@ -1,7 +1,6 @@
 // Regression guard for kumiko-framework#1187: proves the config
-// KEK-rotation job handles a real version-N → version-N+1 rotation, not
-// just legacy-format → envelope (see encrypted-legacy-migration.integration
-// .test.ts for that story). Modeled directly on auth-mfa's
+// KEK-rotation job handles a real version-N → version-N+1 rotation. Modeled
+// directly on auth-mfa's
 // reencrypt-job.integration.test.ts, which is the reference regression
 // guard for this exact bug class (kumiko-framework#266 Step 8): rotation
 // must go through executor.update() (a real event), not a raw UPDATE on

package/src/config/feature.ts

@@ -58,10 +58,8 @@ export function createConfigFeature(): FeatureDefinition {
       readiness: r.queryHandler(readinessQuery),
     };
 
-    // Migration + KEK-rotation for encrypted values (legacy-format →
-    // envelope, old kekVersion → current). Manual trigger — ops runs it
-    // once after adding a new master key version or before retiring the
-    // legacy CONFIG_ENCRYPTION_KEY.
+    // KEK-rotation for encrypted values. Manual trigger — ops runs it once
+    // after adding a new master key version.
     r.job("reencrypt", { trigger: { manual: true } }, reencryptJob);
 
     r.translations({ keys: CONFIG_FEATURE_I18N });

package/src/config/handlers/set.write.ts

@@ -135,7 +135,13 @@ export const setWrite = defineWriteHandler({
         tenantId,
         userId: String(event.user.id),
       };
-      serialized = await encryptPiiValueForSubject(kms, subject, serialized, kmsCtx);
+      serialized = await encryptPiiValueForSubject(
+        kms,
+        subject,
+        serialized,
+        kmsCtx,
+        event.payload.key,
+      );
     }
 
     const existing = await findConfigRow(db, event.payload.key, tenantId, userId);

package/src/config/resolver.ts

@@ -117,7 +117,7 @@ async function decryptPiiEncrypted(raw: string, qualifiedKey: string): Promise<s
     });
   }
   const kmsCtx: KmsContext = { requestId: requestContext.get()?.requestId ?? "config:resolver" };
-  return decryptPiiValueForSubject(kms, raw, kmsCtx);
+  return decryptPiiValueForSubject(kms, raw, kmsCtx, qualifiedKey);
 }
 
 // backing="secrets" keys store their value in the secrets store (flat per

package/src/custom-fields/__tests__/user-data-rights.integration.test.ts

@@ -14,6 +14,7 @@
 //     rows on strategy "delete".
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   buildEntityTable,
@@ -137,6 +138,7 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [
       createUserFeature(),
+      authFoundationFeature,
       createSessionsFeature(),
       createDataRetentionFeature(),
       createComplianceProfilesFeature(),

package/src/delivery/handlers/log.query.ts

@@ -31,7 +31,7 @@ export const logQuery = defineQueryHandler({
           ...row,
           recipientAddress:
             typeof row["recipientAddress"] === "string"
-              ? await decryptStoredPii(row["recipientAddress"], "delivery-log")
+              ? await decryptStoredPii(row["recipientAddress"], "recipientAddress", "delivery-log")
               : row["recipientAddress"],
         })),
       ),

package/src/files-provider-s3/__tests__/s3-provider.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { describeFileProviderContract } from "@cosmicdrift/kumiko-framework/testing";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { createS3ProviderFromEnv } from "../env-helper";
 import { createS3Provider } from "../s3-provider";
@@ -219,3 +220,9 @@ describe("createS3ProviderFromEnv", () => {
     expect(() => createS3ProviderFromEnv("NON_EXISTENT_PREFIX_")).toThrow(/missing_env/);
   });
 });
+
+describeFileProviderContract("S3Provider (Minio)", () => provider);
+
+describeFileProviderContract("createS3ProviderFromEnv (Minio)", () =>
+  createS3ProviderFromEnv("MINIO_"),
+);

package/src/folders/web/__tests__/folder-manager.test.tsx

@@ -165,11 +165,12 @@ describe("FolderManager filing mode", () => {
     await waitFor(() => expect(onReassigned).toHaveBeenCalled());
   });
 
-  test("the in-tree new-folder row opens a draft; submitting (Enter) creates a root folder", async () => {
+  test("the in-tree new-folder row opens a draft; submitting (Enter) creates a root folder and reassigns", async () => {
     folderRows = [];
+    const onReassigned = mock(() => {});
     render(
       <Wrapper>
-        <FolderManager />
+        <FolderManager filing={filingWith(onReassigned)} />
       </Wrapper>,
     );
     fireEvent.click(screen.getByTestId("folder-manager-new-root"));
@@ -180,6 +181,30 @@ describe("FolderManager filing mode", () => {
     await waitFor(() =>
       expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.createFolder, { name: "Inbox" }),
     );
+    await waitFor(() => expect(onReassigned).toHaveBeenCalled());
+  });
+
+  test("renaming a folder dispatches update-folder and reassigns", async () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    const onReassigned = mock(() => {});
+    render(
+      <Wrapper>
+        <FolderManager filing={filingWith(onReassigned)} />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByTestId("folder-rename-f1"));
+    fireEvent.change(document.getElementById("folder-manager-draft") as HTMLInputElement, {
+      target: { value: "Renamed" },
+    });
+    fireEvent.submit(screen.getByTestId("folder-manager-draft"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.updateFolder, {
+        id: "f1",
+        version: 1,
+        changes: { name: "Renamed" },
+      }),
+    );
+    await waitFor(() => expect(onReassigned).toHaveBeenCalled());
   });
 
   test("a mixed-type tree files each leaf under its own entityType (per-leaf override + fallback)", async () => {

package/src/inbound-mail-foundation/__tests__/account-state.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MailAccountEventPayload } from "../events";
+import { loadCurrentMailAccountPayload } from "../handlers/account-state";
+
+function ctxWithEvents(
+  payloads: readonly MailAccountEventPayload[],
+): Pick<HandlerContext, "loadAggregate"> {
+  return {
+    loadAggregate: async () =>
+      payloads.map((payload) => ({
+        // @cast-boundary test fixture — only `payload` is read by the function under test
+        payload,
+      })) as unknown as Awaited<ReturnType<HandlerContext["loadAggregate"]>>,
+  };
+}
+
+describe("loadCurrentMailAccountPayload", () => {
+  test("returns undefined when the aggregate has no events", async () => {
+    const ctx = ctxWithEvents([]);
+    expect(await loadCurrentMailAccountPayload(ctx, "acc-1")).toBeUndefined();
+  });
+
+  test("returns the payload of the LAST event — full-snapshot semantics", async () => {
+    const first = { status: "active" } as unknown as MailAccountEventPayload;
+    const last = { status: "degraded" } as unknown as MailAccountEventPayload;
+    const ctx = ctxWithEvents([first, last]);
+    expect(await loadCurrentMailAccountPayload(ctx, "acc-1")).toBe(last);
+  });
+});

package/src/inbound-mail-foundation/__tests__/inbound-mail-foundation.integration.test.ts

@@ -274,12 +274,13 @@ describe("scenario 2b: ingest-message — Thread-Rollup selbstkorrigierend statt
     );
     const threadAggId = mailThreadAggregateId(admin.tenantId, "mid:self-heal-root@example.com");
 
-    // Simuliert exakt den Drift, den ein Race auf getStreamVersion (siehe
-    // Handler-Kommentar Schritt 5) verursachen kann: 2 Message-Rows liegen
-    // vor, aber der ZULETZT geschriebene Thread-Event traegt einen zu
-    // niedrigen Snapshot (previousCount+1 aus einer stale-Read). Das Event
-    // ist die Quelle, die previousCount+1 (alter Code) liest — der Live-
-    // COUNT (neuer Code) ignoriert es und liest read_inbound_messages neu.
+    // Simuliert den Snapshot-Drift, den ein verlorener Version-Conflict-
+    // Retry (siehe Handler-Kommentar Schritt 5) theoretisch trotz der
+    // Retry-Schleife hinterlassen könnte: 2 Message-Rows liegen vor, aber
+    // der ZULETZT geschriebene Thread-Event trägt einen zu niedrigen
+    // Snapshot. Der neue ingest liest den Live-COUNT gegen
+    // read_inbound_messages neu statt dem Event-Snapshot zu vertrauen —
+    // der Fehler ist selbstkorrigierend, nicht kumulativ.
     const expectedVersion = await getStreamVersion(db, threadAggId, admin.tenantId);
     const corruptedPayload: MailThreadEventPayload = {
       threadKey: "mid:self-heal-root@example.com",
@@ -319,6 +320,56 @@ describe("scenario 2b: ingest-message — Thread-Rollup selbstkorrigierend statt
   });
 });
 
+describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #1229)", () => {
+  // Probabilistic — looped per house convention (mehrere Durchläufe, z.B.
+  // 20x): the version-conflict race between two step-5 thread-rollup
+  // appends only fires on genuine transaction-timing interleaving, which
+  // a single run can't force deterministically.
+  const ITERATIONS = 20;
+  const CONCURRENCY = 3;
+
+  test(`${CONCURRENCY} concurrent ingests of different messages in the same thread never 500 and converge on the correct messageCount, ${ITERATIONS} rounds`, async () => {
+    const admin = adminFor(4022);
+    const accountId = await connectSharedAccount(admin);
+
+    for (let round = 0; round < ITERATIONS; round++) {
+      const rootMessageIdHeader = `race-root-${round}@example.com`;
+
+      const responses = await Promise.all(
+        Array.from({ length: CONCURRENCY }, (_, n) =>
+          stack.http.write(
+            InboundMailFoundationHandlers.ingestMessage,
+            ingestPayload(accountId, {
+              providerMessageId: `race-${round}-${n}`,
+              messageIdHeader: `race-${round}-${n}@example.com`,
+              references: [rootMessageIdHeader],
+            }),
+            admin,
+          ),
+        ),
+      );
+
+      // No writer's transaction fails with a 500 from the thread-rollup
+      // version conflict — each of the CONCURRENCY distinct messages is
+      // its own aggregate, so step 4 never races; only step 5 (shared
+      // threadAggId) does, and the bounded retry loop must absorb it.
+      for (const res of responses) {
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { isSuccess: boolean; data: { duplicate: boolean } };
+        expect(body.isSuccess).toBe(true);
+        expect(body.data.duplicate).toBe(false);
+      }
+
+      const threadAggId = mailThreadAggregateId(admin.tenantId, `mid:${rootMessageIdHeader}`);
+      const threadRows = await selectMany(db, mailThreadsProjectionTable, { id: threadAggId });
+      expect(threadRows).toHaveLength(1);
+      // Every message's contribution landed — no drift from a silently
+      // stale-read-and-succeed append (the bug the retry loop replaces).
+      expect(threadRows[0]?.["messageCount"]).toBe(CONCURRENCY);
+    }
+  });
+});
+
 describe("scenario 3: Scope-Sichtbarkeit (persönliches Postfach)", () => {
   test("Messages eines user-scoped Accounts sieht nur der Owner (+ TenantAdmin)", async () => {
     const tenantNumber = 4003;

package/src/inbound-mail-foundation/__tests__/inbound-mail-provider-contract.ts

@@ -0,0 +1,93 @@
+// Shared contract for inbound-mail-foundation provider plugins — analog
+// to describeKmsAdapterContract (packages/framework/src/crypto/__tests__).
+// Cursor payloads are provider-opaque here (imap: {uidValidity,lastUid},
+// inmemory: {offset}) — the contract only round-trips nextCursor, never
+// inspects its shape. Error-path behaviour stays provider-specific
+// (verify/wrong-credentials semantics don't line up across providers).
+
+import { describe, expect, test } from "bun:test";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "../types";
+
+export type InboundMailProviderContractFixture = {
+  readonly plugin: InboundMailProviderPlugin;
+  readonly ctx: InboundMailContext;
+  readonly account: MailAccountRecord;
+  /** Injects a message with the given subject into the provider's
+   *  backing store (imap: sends real mail; inmemory: seedInboundMessage). */
+  readonly seed: (subject: string) => Promise<void>;
+};
+
+export function describeInboundMailProviderContract(
+  name: string,
+  factory: () => InboundMailProviderContractFixture | Promise<InboundMailProviderContractFixture>,
+  opts?: { readonly skip?: boolean },
+): void {
+  // Eager sync probe so a provider without `watch` produces a visible
+  // test.skip instead of a silent 0-assertion pass (#1337). Both current
+  // factories (imap, inmemory) are sync object literals; an async factory
+  // falls back to the old runtime `if (!plugin.watch) return` check below.
+  const probe = factory();
+  const watchProbe = probe instanceof Promise ? undefined : Boolean(probe.plugin.watch);
+
+  describe(`${name} — InboundMailProviderPlugin contract`, () => {
+    const t = opts?.skip ? test.skip : test;
+    t("verify resolves for a valid account", async () => {
+      const { plugin, ctx, account } = await factory();
+      await expect(plugin.verify(ctx, account)).resolves.toBeUndefined();
+    });
+
+    t(
+      "fetch: backfill picks up a seeded message, incremental cursor finds nothing new",
+      async () => {
+        const { plugin, ctx, account, seed } = await factory();
+        const subject = `contract-${crypto.randomUUID()}`;
+        await seed(subject);
+
+        const first = await plugin.fetch(ctx, account, null, {
+          backfillWindowDays: 1,
+          maxMessages: 50,
+        });
+        expect(first.messages.some((m) => m.subject === subject)).toBe(true);
+
+        const second = await plugin.fetch(ctx, account, first.nextCursor, {
+          backfillWindowDays: 1,
+          maxMessages: 50,
+        });
+        expect(second.messages.some((m) => m.subject === subject)).toBe(false);
+      },
+    );
+
+    const watchTest = watchProbe === false ? test.skip : t;
+    watchTest("watch: pushes a seeded message via onMessages", async () => {
+      const { plugin, ctx, account, seed } = await factory();
+      if (!plugin.watch) return; // fallback for an async factory (watchProbe undefined)
+      const subject = `contract-watch-${crypto.randomUUID()}`;
+
+      const pushed = new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("watch push not received within 5s")),
+          5_000,
+        );
+        void plugin
+          .watch?.(ctx, account, {
+            onMessages: async (msgs) => {
+              if (msgs.some((m) => m.subject === subject)) {
+                clearTimeout(timer);
+                resolve();
+              }
+            },
+            onError: (err) => {
+              clearTimeout(timer);
+              reject(err instanceof Error ? err : new Error(String(err)));
+            },
+          })
+          .then((stop) => {
+            void seed(subject).catch(reject);
+            void pushed.finally(() => void stop().catch(() => {}));
+          }, reject);
+      });
+
+      await pushed;
+    });
+  });
+}