@cosmicdrift/kumiko-bundled-features 0.165.0 → 2.0.0

package/src/feature-toggles/__tests__/compose-tier-resolver.test.ts

@@ -40,8 +40,16 @@ const testRegistry = createRegistry([
   }),
 ]);
 
+// Mirrors tier-engine's real resolver contract (tier-engine/feature.ts's
+// mergeAlwaysOn calls): SYSTEM_TENANT_ID always includes at least the
+// always-on features merged in, even when zero tiers grant anything —
+// tests exercising "no tier grants this feature" must still see a non-empty
+// SYSTEM_TENANT_ID union, exactly like a real app always has.
 function tierResolverGranting(...features: readonly string[]): EffectiveFeaturesResolver {
-  return ((_tenantId: TenantId) => new Set(features)) as EffectiveFeaturesResolver;
+  return (tenantId: TenantId) =>
+    tenantId === SYSTEM_TENANT_ID
+      ? new Set([...features, "always-on-stand-in"])
+      : new Set(features);
 }
 
 describe("composeTierResolverWithGlobalToggles", () => {
@@ -77,10 +85,10 @@ describe("composeTierResolverWithGlobalToggles", () => {
     // nothing (e.g. Free). An operator flipping the global row to true
     // must not leak it in — that decision belongs to the tier, not the
     // toggle.
-    const tierResolver = ((tenantId: TenantId) =>
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
       tenantId === SYSTEM_TENANT_ID
         ? new Set(["personal-access-tokens"]) // union of all tiers' features
-        : new Set<string>()) as EffectiveFeaturesResolver; // this tenant's (Free) tier grants nothing
+        : new Set<string>(); // this tenant's (Free) tier grants nothing
     const runtime = new GlobalFeatureToggleRuntime(fakeDb, testRegistry);
     runtime.apply("personal-access-tokens", true);
     const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, testRegistry);
@@ -141,11 +149,46 @@ describe("composeTierResolverWithGlobalToggles", () => {
     expect([...composed("t1" as TenantId)]).toEqual(["auth-self-registration"]);
   });
 
+  test("kumiko-framework#1479/2: an empty SYSTEM_TENANT_ID union throws instead of silently disabling all tier-gating", () => {
+    // A tierResolver that doesn't implement the SYSTEM_TENANT_ID convention
+    // at all (e.g. always returns per-tenant grants, never the union) —
+    // the old code would treat this as "zero tier-managed features", so
+    // EVERY toggleable feature falls through to the tier-unaware cascade
+    // and tier-gating is silently defeated.
+    const brokenTierResolver: EffectiveFeaturesResolver = (_tenantId: TenantId) =>
+      new Set<string>();
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, testRegistry);
+    const composed = composeTierResolverWithGlobalToggles(
+      brokenTierResolver,
+      runtime,
+      testRegistry,
+    );
+    expect(() => composed("t1" as TenantId)).toThrow(/SYSTEM_TENANT_ID/);
+  });
+
+  test("kumiko-framework#1479/2: tierManaged is computed lazily — a resolver not ready at compose-time is fine as long as it's ready by first call", () => {
+    let ready = false;
+    const lateBoundResolver: EffectiveFeaturesResolver = (tenantId: TenantId) => {
+      if (!ready) throw new Error("tierResolver not wired yet");
+      return tenantId === SYSTEM_TENANT_ID
+        ? new Set(["personal-access-tokens"])
+        : new Set<string>();
+    };
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, testRegistry);
+    // Composing must NOT eagerly call tierResolver(SYSTEM_TENANT_ID) — the
+    // late-bound holder pattern (run-dev-app.ts) builds the real resolver
+    // only after composeTierResolverWithGlobalToggles has already run.
+    const composed = composeTierResolverWithGlobalToggles(lateBoundResolver, runtime, testRegistry);
+    ready = true;
+    expect(() => composed("t1" as TenantId)).not.toThrow();
+  });
+
   test("preserves the tier resolver's trialGate", async () => {
     const runtime = new GlobalFeatureToggleRuntime(fakeDb, testRegistry);
-    const tierResolver = tierResolverGranting();
     const trialGate = async (_tenantId: TenantId, _featureName: string) => true;
-    Object.assign(tierResolver, { trialGate });
+    const tierResolver: EffectiveFeaturesResolver = Object.assign(tierResolverGranting(), {
+      trialGate,
+    });
 
     const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, testRegistry);
     expect(composed.trialGate).toBe(trialGate);
@@ -177,10 +220,10 @@ describe("composeTierResolverWithGlobalToggles — non-toggleable + requires() i
     // otherwise composeTierResolverWithGlobalToggles' `!tierManaged.has()`
     // filter would incorrectly drop it (tier-managed but absent from this
     // tenant's own tier subset).
-    const tierResolver = ((tenantId: TenantId) =>
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
       tenantId === SYSTEM_TENANT_ID
         ? new Set(["tenant", "personal-access-tokens"])
-        : new Set(["tenant"])) as EffectiveFeaturesResolver;
+        : new Set(["tenant"]);
     const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
     const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
     expect([...composed("t1" as TenantId)]).toContain("tenant");
@@ -190,12 +233,72 @@ describe("composeTierResolverWithGlobalToggles — non-toggleable + requires() i
     // "pat-companion" is tier-unaware (no tier ever lists it) but requires
     // "personal-access-tokens", which IS tier-managed and this tenant's own
     // tier grants nothing — the dependency must not silently resolve true.
-    const tierResolver = ((tenantId: TenantId) =>
-      tenantId === SYSTEM_TENANT_ID
-        ? new Set(["personal-access-tokens"])
-        : new Set<string>()) as EffectiveFeaturesResolver;
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
+      tenantId === SYSTEM_TENANT_ID ? new Set(["personal-access-tokens"]) : new Set<string>();
     const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
     const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
     expect([...composed("t1" as TenantId)]).not.toContain("pat-companion");
   });
+
+  test("kumiko-framework#1471/1: a tier-granted feature whose requires() dependency is globally disabled is excluded too", () => {
+    // "pat-companion" IS in this tenant's tier grant this time (unlike the
+    // test above) — the tenant's tier says yes, but its requires()
+    // dependency "personal-access-tokens" is killed globally via override.
+    // The old code only checked `readOverride(name) !== false` on
+    // "pat-companion" itself (which has no override, so it stayed) without
+    // ever re-running the requires() cascade over the tier-granted set —
+    // exactly the class of bug #1471/1 describes (channel-email staying up
+    // after its `delivery` dependency is killed).
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
+      tenantId === SYSTEM_TENANT_ID
+        ? new Set(["personal-access-tokens", "pat-companion"])
+        : new Set(["personal-access-tokens", "pat-companion"]);
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
+    runtime.apply("personal-access-tokens", false);
+    const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
+    const result = [...composed("t1" as TenantId)];
+    expect(result).not.toContain("personal-access-tokens");
+    expect(result).not.toContain("pat-companion");
+  });
+
+  test("kumiko-framework#1471/2: a global override cannot disable a non-toggleable (always-on) feature", () => {
+    // "tenant" has no r.toggleable() call at all — computeEffectiveFeatures'
+    // Rule 1 says non-toggleable features ignore overrides entirely. The old
+    // code applied `readOverride(name) !== false` to every name in tierSet
+    // with no toggleability check, so a stray override row (seed script,
+    // ops SQL, or a feature that used to be toggleable and had `r.toggleable()`
+    // removed) could disable an always-on feature outright.
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
+      tenantId === SYSTEM_TENANT_ID ? new Set(["tenant"]) : new Set(["tenant"]);
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
+    runtime.apply("tenant", false);
+    const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
+    expect([...composed("t1" as TenantId)]).toContain("tenant");
+  });
+
+  test("framework#1528: a resolver satisfying the emptiness guard but not merging always-on per-tenant still surfaces the always-on feature", () => {
+    // Custom composeApp resolver: implements the SYSTEM_TENANT_ID convention
+    // (union includes "tenant") but, unlike tier-engine's own mergeAlwaysOn,
+    // returns only the tier-only set for real tenants. Before the Rule-1
+    // structural fix, "tenant" landed in the raw (unfiltered) tierManaged set
+    // and got skipped by the globalCascade loop too, since it's absent from
+    // this tenant's own tierSet — a silent 403 on every always-on handler.
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
+      tenantId === SYSTEM_TENANT_ID
+        ? new Set(["tenant", "personal-access-tokens"])
+        : new Set<string>();
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
+    const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
+    expect([...composed("t1" as TenantId)]).toContain("tenant");
+  });
+
+  test("a tier-granted name with no registry entry is dropped by the requires() cascade fixpoint", () => {
+    const tierResolver: EffectiveFeaturesResolver = (tenantId: TenantId) =>
+      tenantId === SYSTEM_TENANT_ID
+        ? new Set(["tenant", "ghost-feature"])
+        : new Set(["tenant", "ghost-feature"]);
+    const runtime = new GlobalFeatureToggleRuntime(fakeDb, registry);
+    const composed = composeTierResolverWithGlobalToggles(tierResolver, runtime, registry);
+    expect([...composed("t1" as TenantId)]).not.toContain("ghost-feature");
+  });
 });

package/src/feature-toggles/compose-tier-resolver.ts

@@ -1,6 +1,6 @@
 import {
-  computeEffectiveFeatures,
   type EffectiveFeaturesResolver,
+  isToggleableFeature,
   type Registry,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -39,24 +39,93 @@ import type { GlobalFeatureToggleRuntime } from "./toggle-runtime";
 export function composeTierResolverWithGlobalToggles(
   tierResolver: EffectiveFeaturesResolver,
   toggleRuntime: GlobalFeatureToggleRuntime,
+  // registry needed for toggleability lookups; toggleRuntime keeps its own registry reference private.
   registry: Registry,
 ): EffectiveFeaturesResolver {
-  const tierManaged = tierResolver(SYSTEM_TENANT_ID);
+  // Lazy + memoized: computed on first composed(tenantId) call, not at
+  // compose-time. Late-bound holder wiring (e.g. run-dev-app.ts's tier
+  // resolver plugin) may not have its real tierResolver built yet when
+  // composeTierResolverWithGlobalToggles itself runs.
+  let tierManaged: ReadonlySet<string> | undefined;
+
+  const composed: EffectiveFeaturesResolver = (tenantId) => {
+    if (tierManaged === undefined) {
+      const managed = tierResolver(SYSTEM_TENANT_ID);
+      // fail-loud: an empty union means the resolver doesn't implement the SYSTEM_TENANT_ID convention at all.
+      if (managed.size === 0) {
+        throw new Error(
+          "composeTierResolverWithGlobalToggles: tierResolver(SYSTEM_TENANT_ID) " +
+            "returned an empty set. tier-engine's SYSTEM_TENANT_ID convention " +
+            "(union of every tier's features, plus always-on features) must " +
+            "never be empty — an empty result means the tierResolver passed in " +
+            "doesn't implement that convention, which would silently disable " +
+            "all tier-gating (every feature would be treated as tier-unaware).",
+        );
+      }
+      // Structural Rule 1: only the TOGGLEABLE subset of the union is tier-managed.
+      // Non-toggleable (always-on) names must keep reaching `result` through the
+      // globalCascade loop below even if this resolver's SYSTEM_TENANT_ID answer
+      // satisfies the emptiness guard above without also merging always-on into
+      // every per-tenant tierSet (framework#1528).
+      tierManaged = new Set(
+        [...managed].filter((name) => {
+          const feature = registry.getFeature(name);
+          return feature !== undefined && isToggleableFeature(feature);
+        }),
+      );
+    }
 
-  const composed = ((tenantId) => {
     const tierSet = tierResolver(tenantId);
     const result = new Set<string>();
     for (const name of tierSet) {
-      if (toggleRuntime.readOverride(name) !== false) result.add(name);
+      // Only a toggleable feature's override can narrow the tier's grant —
+      // computeEffectiveFeatures' Rule 1 ignores overrides for features
+      // without a toggleableDefault, and an override row can otherwise
+      // reach a non-toggleable feature via seed-scripts/ops-SQL/an
+      // r.toggleable() removal after the fact (readOverride/refresh() have
+      // no toggleability gate of their own).
+      const feature = registry.getFeature(name);
+      const isToggleable = feature !== undefined && isToggleableFeature(feature);
+      if (!isToggleable || toggleRuntime.readOverride(name) !== false) {
+        result.add(name);
+      }
     }
-    const globalCascade = computeEffectiveFeatures(registry, (name) =>
-      toggleRuntime.readOverride(name),
-    );
+    // toggleRuntime.effectiveFeatures() already applies computeEffectiveFeatures'
+    // full rule set (toggleableDefault ?? override, THEN the requires() cascade)
+    // — reusing it here instead of calling computeEffectiveFeatures directly
+    // keeps this in lockstep with the runtime's own dispatcher-facing callback.
+    const globalCascade = toggleRuntime.effectiveFeatures();
     for (const name of globalCascade) {
       if (!tierManaged.has(name)) result.add(name);
     }
+
+    // requires() cascade over the combined result: a feature narrowed off by
+    // either loop above (tier-managed override, or absent from both sets)
+    // must also drop anything that itself requires it — computeEffectiveFeatures
+    // enforces this for its own single reader, but tierSet's membership isn't
+    // reader-driven, so the cascade has to be re-applied over the union.
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const name of [...result]) {
+        const feature = registry.getFeature(name);
+        if (!feature) {
+          result.delete(name);
+          changed = true;
+          continue;
+        }
+        for (const dep of feature.requires) {
+          if (!result.has(dep)) {
+            result.delete(name);
+            changed = true;
+            break;
+          }
+        }
+      }
+    }
+
     return result;
-  }) as EffectiveFeaturesResolver;
+  };
 
   if (tierResolver.trialGate) {
     return Object.assign(composed, { trialGate: tierResolver.trialGate });

package/src/feature-toggles/global-feature-state-table.ts

@@ -1,6 +1,6 @@
+import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
-  defineUnmanagedTable,
   type EntityTableMeta,
   instant,
   integer,
@@ -31,14 +31,17 @@ export const globalFeatureStateTable = pgTable("store_global_feature_state", {
 
 // r.storeTable meta — without this, collectTableMetas(FEATURES) never
 // sees the table, so `kumiko schema generate` reports no changes and no
-// app ever gets a migration for it (framework gap, not app-local).
-export const globalFeatureStateTableMeta: EntityTableMeta = defineUnmanagedTable({
-  tableName: "store_global_feature_state",
-  columns: [
-    { name: "feature_name", pgType: "text", notNull: true, primaryKey: true },
-    { name: "enabled", pgType: "boolean", notNull: true },
-    { name: "version", pgType: "integer", notNull: true, defaultSql: "1" },
-    { name: "updated_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
-    { name: "updated_by", pgType: "text", notNull: false },
-  ],
-});
+// app ever gets a migration for it (framework gap, not app-local). Derived
+// from the pgTable above instead of hand-written a second time — the two
+// used to drift independently (framework#1529): a column added only to
+// the pgTable made queries type-check while the migration generator stayed
+// blind to it, failing in prod with "column ... does not exist" while every
+// mocked-stack test stayed green.
+const derivedMeta = asEntityTableMeta(globalFeatureStateTable);
+if (!derivedMeta) {
+  throw new Error(
+    "global-feature-state-table: asEntityTableMeta(globalFeatureStateTable) returned undefined " +
+      "— the pgTable definition no longer round-trips through the unmanaged-table meta builder.",
+  );
+}
+export const globalFeatureStateTableMeta: EntityTableMeta = derivedMeta;

package/src/files-provider-s3/s3-provider.ts

@@ -1,4 +1,8 @@
-import type { FileStorageProvider, SignedUrlOptions } from "@cosmicdrift/kumiko-framework/files";
+import {
+  assertSafeStorageKey,
+  type FileStorageProvider,
+  type SignedUrlOptions,
+} from "@cosmicdrift/kumiko-framework/files";
 
 // =============================================================================
 // Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
@@ -72,10 +76,12 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
 
   return {
     async write(key, data, mimeType): Promise<void> {
+      assertSafeStorageKey(key);
       await client.write(key, data, mimeType !== undefined ? { type: mimeType } : undefined);
     },
 
     async writeStream(key, source, options): Promise<void> {
+      assertSafeStorageKey(key);
       // Echtes multipart-streaming via Bun's S3-Writer — partSize steuert die
       // Part-Boundary intern (AWS/R2 verlangen non-final Parts >= 5 MiB,
       // sonst EntityTooSmall beim CompleteMultipartUpload). Manuelles flush()
@@ -96,10 +102,12 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
     },
 
     async read(key): Promise<Uint8Array> {
+      assertSafeStorageKey(key);
       return new Uint8Array(await client.file(key).arrayBuffer());
     },
 
     readStream(key): AsyncIterable<Uint8Array> {
+      assertSafeStorageKey(key);
       // Lazy: erst beim ersten chunk-pull wird der GET-Request abgesetzt.
       // Existiert der Key nicht, faellt der Error genau dort (nicht beim
       // readStream-Aufruf) — gleiches Lazy-Verhalten wie inmemory + local.
@@ -113,10 +121,12 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
     },
 
     async delete(key): Promise<void> {
+      assertSafeStorageKey(key);
       await client.delete(key);
     },
 
     async exists(key): Promise<boolean> {
+      assertSafeStorageKey(key);
       return client.exists(key);
     },
 
@@ -125,6 +135,7 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       expiresInSeconds: number,
       options?: SignedUrlOptions,
     ): Promise<string> {
+      assertSafeStorageKey(key);
       // contentDisposition wird von Bun als response-content-disposition
       // Query-Param signiert (Response-Override fuer den GET-Download) —
       // der Browser sieht den Original-Dateinamen statt des UUID-Keys.

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

@@ -22,12 +22,14 @@ import {
   PII_ERASED_SENTINEL,
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import {
   append,
   createEventsTable,
   getStreamVersion,
   loadAggregate,
+  VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/event-store";
 import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
@@ -37,6 +39,7 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
 import {
   createComplianceProfilesFeature,
   tenantComplianceProfileEntity,
@@ -54,6 +57,7 @@ import {
   type MailThreadEventPayload,
 } from "../events";
 import { inboundMailFoundationFeature } from "../feature";
+import { ingestMessageHandler } from "../handlers/ingest-message.write";
 import {
   inboundMessagesProjectionTable,
   mailAccountsProjectionTable,
@@ -370,6 +374,79 @@ describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #
   });
 });
 
+describe("scenario 2d: ingest-message — thread-rollup retry exhaustion (#1229)", () => {
+  // The version-conflict retry loop (THREAD_ROLLUP_MAX_ATTEMPTS = 5) is
+  // exercised by scenario 2c above only on its happy path (some attempt
+  // within the bound eventually wins). New behavior added alongside it —
+  // exhausting all 5 attempts — is untested: does it actually surface as an
+  // InternalError instead of silently persisting a stale messageCount?
+  // Forces exhaustion deterministically by calling the handler directly
+  // with a ctx whose tryAppendEvent always loses the version-conflict race
+  // for the thread aggregate specifically (the message-append itself still
+  // goes through a real, conflict-free append — there's no concurrent
+  // writer for a brand-new message aggregateId).
+  //
+  // Honest scope: this drives the handler directly (no dispatcher, no
+  // enclosing TX), same as reindex-entity-job's direct-call tests — it
+  // does NOT exercise the dispatcher's own TX-rollback-on-throw behavior,
+  // only that the handler itself throws instead of returning success after
+  // exhausting the attempts.
+  test("5 lost version-conflict races → InternalError, not a silent success", async () => {
+    const admin = adminFor(4023);
+    const accountId = await connectSharedAccount(admin);
+    const messageIdHeader = "exhaustion-root@example.com";
+
+    const tenantDb = createTenantDb(db, admin.tenantId, "system");
+    let threadAppendAttempts = 0;
+    const ctx = {
+      db: tenantDb,
+      registry: stack.registry,
+      ...bridgeStub({ user: admin }),
+      loadAggregate: (aggregateId: string) => loadAggregate(db, aggregateId, admin.tenantId),
+      tryAppendEvent: async (args: {
+        aggregateId: string;
+        aggregateType: string;
+        type: string;
+        payload: unknown;
+        headers?: unknown;
+      }) => {
+        if (args.aggregateType === MAIL_THREAD_AGGREGATE_TYPE) {
+          threadAppendAttempts++;
+          return { ok: false as const, conflict: new VersionConflictError(args.aggregateId, 0) };
+        }
+        // Step 4 (message append): fresh aggregateId, no concurrent writer
+        // in this test — a real, conflict-free append via expectedVersion 0.
+        const event = await append(db, {
+          aggregateId: args.aggregateId,
+          aggregateType: args.aggregateType,
+          tenantId: admin.tenantId,
+          expectedVersion: 0,
+          type: args.type,
+          payload: args.payload as Record<string, unknown>,
+          metadata: { userId: String(admin.id) },
+        });
+        return { ok: true as const, event };
+      },
+      // @cast-boundary test/framework — hand-built ctx narrower than HandlerContext
+    } as unknown as HandlerContext;
+
+    await expect(
+      ingestMessageHandler.handler(
+        {
+          type: InboundMailFoundationHandlers.ingestMessage,
+          user: admin,
+          payload: ingestPayload(accountId, {
+            providerMessageId: "exhaustion-1",
+            messageIdHeader,
+          }),
+        },
+        ctx,
+      ),
+    ).rejects.toThrow(/lost the version-conflict race 5 times in a row/);
+    expect(threadAppendAttempts).toBe(5);
+  });
+});
+
 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

@@ -20,21 +20,34 @@ export type InboundMailProviderContractFixture = {
 export function describeInboundMailProviderContract(
   name: string,
   factory: () => InboundMailProviderContractFixture | Promise<InboundMailProviderContractFixture>,
-  opts?: { readonly skip?: boolean },
+  opts?: {
+    readonly skip?: boolean;
+    // Whether the provider implements `watch` — read from the plugin's
+    // module-level export (e.g. `Boolean(imapInboundMailPlugin.watch)`),
+    // not by calling `factory()`. Calling the factory eagerly to probe
+    // this (#1337) ran the imap caller's fixture construction even when
+    // `skip` was true (the exact case the skip exists to avoid), and left
+    // an eager Promise unawaited/uncaught on an async factory. Defaults to
+    // true (run the watch test) when omitted.
+    readonly hasWatch?: boolean;
+    // bunfig's global test timeout (15s) is too tight for a live-IMAP
+    // round-trip under CI load — imap-live.integration.test.ts's own
+    // tests already use 20s for the same greenmail server.
+    readonly timeout?: number;
+  },
 ): 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);
+  const timeout = opts?.timeout;
 
   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(
+      "verify resolves for a valid account",
+      async () => {
+        const { plugin, ctx, account } = await factory();
+        await expect(plugin.verify(ctx, account)).resolves.toBeUndefined();
+      },
+      timeout,
+    );
 
     t(
       "fetch: backfill picks up a seeded message, incremental cursor finds nothing new",
@@ -55,39 +68,44 @@ export function describeInboundMailProviderContract(
         });
         expect(second.messages.some((m) => m.subject === subject)).toBe(false);
       },
+      timeout,
     );
 
-    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 watchTest = opts?.hasWatch === false ? test.skip : t;
+    watchTest(
+      "watch: pushes a seeded message via onMessages",
+      async () => {
+        const { plugin, ctx, account, seed } = await factory();
+        if (!plugin.watch) return; // safety net if opts.hasWatch drifted from the plugin
+        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)) {
+        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);
-                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);
-      });
+                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;
-    });
+        await pushed;
+      },
+      timeout,
+    );
   });
 }

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

@@ -295,6 +295,14 @@ describe("watch-supervisor — watch restart + ingest resilience", () => {
       });
 
       emitWatchError(accountId, new Error("socket dropped"));
+      // No assertion here: isWatching(accountId) flips to false as a side
+      // effect of emitWatchError itself (inbound-provider-inmemory's
+      // feature.ts sets state.watch = null before handlers.onError runs),
+      // and the restart re-arms fast enough that the persisted `backoff:`
+      // projection state isn't reliably observable between the two either
+      // — asserting either one here pins test-helper bookkeeping, not
+      // production behavior. The real assertions are below: the watch
+      // recovers, and the account stays active with a valid watchState.
 
       await waitFor(() => {
         expect(isWatching(accountId)).toBe(true);
@@ -302,7 +310,7 @@ describe("watch-supervisor — watch restart + ingest resilience", () => {
 
       const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
       expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.active);
-      expect(String(accounts[0]?.["watchState"])).toMatch(/^watching|backoff:/);
+      expect(String(accounts[0]?.["watchState"])).toMatch(/^(watching|backoff:)/);
     } finally {
       await supervisor.stop();
     }