@prosopo/user-access-policy 3.9.0 → 3.10.0

package/src/redis/reader/redisAggregate.ts

@@ -29,6 +29,7 @@ export const aggregateRedisKeys = async (
 	query: string,
 	logger: Logger,
 	batchHandler?: (keys: string[]) => Promise<void>,
+	maxKeys?: number,
 ): Promise<string[]> => {
 	const keyField = "__key";
 
@@ -38,8 +39,13 @@ export const aggregateRedisKeys = async (
 	});
 
 	const foundKeys: string[] = [];
+	let stopRequested = false;
 
 	const addRecordKeys = async (records: object[]) => {
+		if (stopRequested) {
+			return;
+		}
+
 		const parsedRecords = parseRedisRecords(records, recordSchema, logger);
 
 		const recordKeys = parsedRecords.map((record) => record[keyField]);
@@ -47,6 +53,24 @@ export const aggregateRedisKeys = async (
 		if (batchHandler) {
 			await batchHandler(recordKeys);
 		} else {
+			if (
+				maxKeys !== undefined &&
+				foundKeys.length + recordKeys.length > maxKeys
+			) {
+				const remaining = Math.max(0, maxKeys - foundKeys.length);
+				foundKeys.push(...recordKeys.slice(0, remaining));
+				stopRequested = true;
+
+				logger.warn(() => ({
+					msg: "Redis aggregation candidate cap hit; truncating result set. This can suppress less-frequent rules and should be investigated.",
+					data: {
+						maxKeys,
+						query,
+					},
+				}));
+				return;
+			}
+
 			foundKeys.push(...recordKeys);
 
 			logger.debug(() => ({
@@ -68,6 +92,7 @@ export const aggregateRedisKeys = async (
 			LOAD: `@${keyField}`,
 		},
 		addRecordKeys,
+		() => stopRequested,
 	);
 
 	return foundKeys;
@@ -78,6 +103,7 @@ const executeAggregation = async (
 	query: string,
 	aggregateOptions: FtAggregateWithCursorOptions,
 	handleBatch: (records: object[]) => Promise<void>,
+	shouldStop?: () => boolean,
 ): Promise<void> => {
 	const initialReply = await client.ft.aggregateWithCursor(
 		ACCESS_RULES_REDIS_INDEX_NAME,
@@ -89,7 +115,7 @@ const executeAggregation = async (
 
 	let cursor = initialReply.cursor;
 
-	while (0 !== cursor) {
+	while (0 !== cursor && !shouldStop?.()) {
 		const batchReply = await client.ft.cursorRead(
 			ACCESS_RULES_REDIS_INDEX_NAME,
 			cursor,

package/src/redis/reader/redisRulesReader.ts

@@ -30,7 +30,7 @@ import {
 	ACCESS_RULES_REDIS_INDEX_NAME,
 	ACCESS_RULE_REDIS_KEY_PREFIX,
 } from "#policy/redis/redisRuleIndex.js";
-import type { AccessRule } from "#policy/rule.js";
+import { AccessPolicyType, type AccessRule } from "#policy/rule.js";
 import { accessRuleInput } from "#policy/ruleInput/ruleInput.js";
 import type {
 	AccessRuleEntry,
@@ -39,6 +39,91 @@ import type {
 } from "#policy/rulesStorage.js";
 import { aggregateRedisKeys } from "./redisAggregate.js";
 
+// Server-side specificity ranking config.
+//
+// Strict-match findRules (matchingFieldsOnly=true) used to pull every
+// matching rule's hash into Node and sort in JS. With the greedy regression
+// in #2689 this hauled ~1190 hashes per request and pegged provider CPU.
+//
+// The new path lets RediSearch compute specificity itself: one
+// FT.AGGREGATE that filters via the strict AND-of-disjunctions query,
+// counts populated rule fields with APPLY+exists(), sorts by that
+// derived score DESC, and returns only the top-N candidates. Node
+// receives at most TOP_N small records, no HGETALL fanout, no JS rank.
+//
+// TOP_N >> 1 leaves headroom for the deferToVerify filter that runs
+// post-aggregate (a Block rule with deferToVerify is skipped in the
+// blockMiddleware path, so we need a few alternates ready). 20 covers
+// the worst observed concentration of deferToVerify rules per scope by
+// comfortable margin while keeping payload tiny.
+export const SERVER_SIDE_RANK_TOP_N = 20;
+
+// Safety cap for the greedy (admin/internal) path. Generous because
+// admin tooling depends on the full result set; not on the hot
+// per-request path.
+const GREEDY_MAX_CANDIDATES = REDIS_BATCH_SIZE * 10;
+
+// Fields that contribute one specificity point each. Mirrors
+// SCALAR_USER_SCOPE_FIELDS + clientId + ip-constraint in
+// blacklistRequestInspector.ruleSpecificity. numericIp and the
+// numericIpMaskMin range are mutually exclusive on a rule (see
+// ruleHasIpConstraint), so `exists(@numericIp) + exists(@numericIpMaskMin)`
+// contributes 1 in practice — never 2 — when applied to writer-produced
+// rules.
+const SPECIFICITY_EXPR = [
+	"exists(@clientId)",
+	"exists(@userId)",
+	"exists(@ja4Hash)",
+	"exists(@headersHash)",
+	"exists(@userAgentHash)",
+	"exists(@headHash)",
+	"exists(@coords)",
+	"exists(@countryCode)",
+	"exists(@asn)",
+	"exists(@numericIp)",
+	"exists(@numericIpMaskMin)",
+].join(" + ");
+
+// Block outranks Restrict on equal specificity (defensive: a request
+// that would match a Block rule must never be downgraded). Note the
+// string literal is lowercase because AccessPolicyType.Block = "block"
+// and getRedisRuleValue serialises via String().
+const SEVERITY_EXPR = `(@type == "${AccessPolicyType.Block}")`;
+
+// Final rank: specificity weighted, severity as tiebreaker on equal
+// specificity. spec*2 + sev fits both into a single sortable float.
+const RANK_EXPR = "(@_spec * 2) + @_sev";
+
+// Every field referenced by SPECIFICITY_EXPR/SEVERITY_EXPR, plus the
+// fields needed to reconstruct an AccessRule downstream. APPLY can only
+// see fields explicitly loaded into the aggregate pipeline, so this
+// list must include every rule attribute the parser cares about.
+const RULE_LOAD_FIELDS = [
+	"@__key",
+	"@type",
+	"@captchaType",
+	"@description",
+	"@solvedImagesCount",
+	"@imageThreshold",
+	"@powDifficulty",
+	"@unsolvedImagesCount",
+	"@frictionlessScore",
+	"@deferToVerify",
+	"@clientId",
+	"@groupId",
+	"@userId",
+	"@ja4Hash",
+	"@headersHash",
+	"@userAgentHash",
+	"@headHash",
+	"@coords",
+	"@countryCode",
+	"@asn",
+	"@numericIp",
+	"@numericIpMaskMin",
+	"@numericIpMaskMax",
+] as const;
+
 export class RedisRulesReader implements AccessRulesReader {
 	constructor(
 		private readonly client: RedisClientType,
@@ -84,47 +169,130 @@ export class RedisRulesReader implements AccessRulesReader {
 			return [];
 		}
 
+		// Hot path: strict-match callers (blockMiddleware /
+		// checkForHardBlock) get server-side specificity ranking via
+		// FT.AGGREGATE — Redis returns the top N candidates already
+		// sorted, no HGETALL fanout. See SPECIFICITY_EXPR / RANK_EXPR
+		// above for the score definition.
+		if (matchingFieldsOnly) {
+			return this.findRulesRanked(filter, query);
+		}
+
+		// Admin / internal callers (greedy mode): keep the FT.SEARCH +
+		// HGETALL fanout path. Cap at REDIS_BATCH_SIZE; truncation past
+		// that point is the known liability tracked in #2689.
+		return this.findRulesGreedy(filter, query);
+	}
+
+	private async findRulesRanked(
+		filter: AccessRulesFilter,
+		query: string,
+	): Promise<AccessRule[]> {
 		try {
-			// Use searchNoContent to get document keys only, then fetch data separately.
-			// This avoids a bug in @redis/search where ft.search crashes with
-			// "Cannot read properties of null (reading 'length')" when a document
-			// is deleted/expired between the index scan and data retrieval.
-			const searchReply = await this.client.ft.searchNoContent(
+			const reply = await this.client.ft.aggregate(
 				ACCESS_RULES_REDIS_INDEX_NAME,
 				query,
 				{
 					DIALECT: REDIS_QUERY_DIALECT,
-					// FT.search doesn't support "unlimited" selects
-					LIMIT: {
-						from: 0,
-						size: REDIS_BATCH_SIZE,
-					},
+					LOAD: [...RULE_LOAD_FIELDS],
+					STEPS: [
+						{ type: "APPLY", expression: SPECIFICITY_EXPR, AS: "_spec" },
+						{ type: "APPLY", expression: SEVERITY_EXPR, AS: "_sev" },
+						{ type: "APPLY", expression: RANK_EXPR, AS: "_rank" },
+						{
+							type: "SORTBY",
+							BY: [{ BY: "@_rank", DIRECTION: "DESC" }],
+							// SORTBY MAX would let RediSearch keep only the
+							// top-N in a bounded heap rather than fully
+							// sorting, but the @redis/search client
+							// serialises MAX *before* DESC and RediSearch
+							// rejects that order ("MISSING ASC or DESC
+							// after sort field (MAX)"). LIMIT below still
+							// trims; SORTBY does a full sort. Acceptable
+							// because the strict-match filter already
+							// keeps the candidate set small in practice.
+						},
+						{ type: "LIMIT", from: 0, size: SERVER_SIDE_RANK_TOP_N },
+					],
 				},
 			);
 
-			if (searchReply.total > 0) {
-				this.logger.debug(() => ({
-					msg: "Executed search query",
-					data: {
-						inspect: util.inspect(
-							{
-								filter: filter,
-								searchReply: searchReply,
-								query: query,
-							},
-							{ depth: null },
-						),
-					},
-				}));
+			if (reply.results.length === 0) {
+				return [];
 			}
 
-			if (searchReply.documents.length === 0) {
+			this.logger.debug(() => ({
+				msg: "Executed ranked search query",
+				data: {
+					inspect: util.inspect(
+						{
+							filter: filter,
+							foundCount: reply.results.length,
+							query: query,
+						},
+						{ depth: null },
+					),
+				},
+			}));
+
+			// FT.AGGREGATE results include the derived _spec/_sev/_rank
+			// fields and the loaded rule fields. parseRedisRecords runs
+			// through zod which ignores the derived fields. __key is
+			// also passed through but unused downstream.
+			return parseRedisRecords(reply.results, accessRuleInput, this.logger);
+		} catch (e) {
+			this.logger.error(() => ({
+				err: e,
+				data: {
+					inspect: util.inspect({ query, filter }, { depth: null }),
+				},
+				msg: "failed to execute ranked search query",
+			}));
+
+			return [];
+		}
+	}
+
+	// Used only by admin / internal callers (matchingFieldsOnly=false).
+	// Not on the per-request blockMiddleware path any more, so the CPU
+	// cost of the HGETALL fanout is acceptable. Same shape as #2689's
+	// aggregate-with-cursor: returns every candidate up to
+	// GREEDY_MAX_CANDIDATES so we don't silently drop matches that
+	// admin tools depend on (e.g. ASN-wide rule listings).
+	private async findRulesGreedy(
+		filter: AccessRulesFilter,
+		query: string,
+	): Promise<AccessRule[]> {
+		try {
+			const ruleKeys = await aggregateRedisKeys(
+				this.client,
+				query,
+				this.logger,
+				undefined,
+				GREEDY_MAX_CANDIDATES,
+			);
+
+			if (ruleKeys.length === 0) {
 				return [];
 			}
 
+			this.logger.debug(() => ({
+				msg: "Executed greedy search query",
+				data: {
+					inspect: util.inspect(
+						{
+							filter: filter,
+							foundCount: ruleKeys.length,
+							query: query,
+						},
+						{ depth: null },
+					),
+				},
+			}));
+
 			const { records } = await fetchRedisHashRecords(
 				this.client,
-				searchReply.documents,
+				ruleKeys,
 				this.logger,
 			);
 
@@ -137,17 +305,9 @@ export class RedisRulesReader implements AccessRulesReader {
 			this.logger.error(() => ({
 				err: e,
 				data: {
-					inspect: util.inspect(
-						{
-							query: query,
-							filter: filter,
-						},
-						{
-							depth: null,
-						},
-					),
+					inspect: util.inspect({ query, filter }, { depth: null }),
 				},
-				msg: "failed to execute search query",
+				msg: "failed to execute greedy search query",
 			}));
 
 			return [];

package/src/tests/redis/redisRulesReaderRank.benchmark.integration.test.ts

@@ -0,0 +1,338 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { chunkIntoBatches, executeBatchesSequentially } from "@prosopo/common";
+import type { Logger } from "@prosopo/logger";
+import {
+	type RedisConnection,
+	createTestRedisConnection,
+	setupRedisIndex,
+} from "@prosopo/redis-client";
+import type { RedisClientType } from "redis";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { RedisRulesReader } from "#policy/redis/reader/redisRulesReader.js";
+import {
+	ACCESS_RULES_REDIS_INDEX_NAME,
+	accessRulesRedisIndex,
+	getAccessRuleRedisKey,
+} from "#policy/redis/redisRuleIndex.js";
+import { getRedisRuleValue } from "#policy/redis/redisRulesWriter.js";
+import { AccessPolicyType, type AccessRule } from "#policy/rule.js";
+import { FilterScopeMatch } from "#policy/rulesStorage.js";
+
+// Production observation on pronode10 (2026-06-15):
+//   - ~7,500 rules in the access-rule index
+//   - greedy + FT.AGGREGATE pulled ~1,190 hashes per request and pegged
+//     provider1 Node thread at ~125% CPU.
+//   - Strict-match + server-side rank pulls at most SERVER_SIDE_RANK_TOP_N
+//     hashes per request, so the cost is independent of total rule count.
+//
+// This benchmark seeds 10k rules with a realistic specificity distribution,
+// runs N findRules calls in matchingFieldsOnly=true mode, and asserts
+// per-call latency stays inside generous CI thresholds. The numbers below
+// are intentionally loose; healthy local runs typically come in 5-10x
+// under cap. The point is to catch regressions where someone re-introduces
+// HGETALL fanout into the hot path.
+
+const RULE_COUNT = 10_000;
+const QUERY_COUNT = 200;
+
+// CI thresholds. Local development on a warm redis container is steady
+// around p50=20ms / p99=25ms over 10k rules; thresholds set ~3-5x above
+// that to absorb noisy shared CI runners. If these start failing
+// regularly, look for changes that re-introduce per-rule HGETALL fanout
+// or break the SORTBY MAX short-circuit on the Redis side.
+const P50_LATENCY_MS = 80;
+const P99_LATENCY_MS = 250;
+
+// Build a deterministic distribution of rules that mirrors production
+// roughly:
+//   ~70% low-specificity (1 field, e.g. ja4-only or country-only)
+//   ~20% medium (2-3 fields, typical anomaly detector emission)
+//   ~10% high (4+ fields, manual portal rules with full scope)
+const buildBenchmarkRule = (i: number): AccessRule => {
+	const bucket = i % 10;
+	const ja4 = `t13d_bench_${(i % 50).toString().padStart(3, "0")}`;
+	const asn = 1000 + (i % 500);
+	// description is included in the content hash that generates the
+	// rule's Redis key, so a unique description ensures every synthetic
+	// rule lands on its own key. It doesn't affect specificity scoring
+	// or the strict-match filter.
+	const description = `bench-rule-${i}`;
+
+	if (bucket < 7) {
+		// low specificity — anomaly detector style
+		const variant = i % 3;
+		if (variant === 0)
+			return { type: AccessPolicyType.Block, description, ja4Hash: ja4 };
+		if (variant === 1)
+			return {
+				type: AccessPolicyType.Block,
+				description,
+				asn,
+			};
+		return {
+			type: AccessPolicyType.Restrict,
+			description,
+			countryCode: `C${i % 30}`,
+		};
+	}
+
+	if (bucket < 9) {
+		// medium specificity — client-scoped + 1-2 fields
+		return {
+			type: AccessPolicyType.Block,
+			description,
+			clientId: `client${i % 20}`,
+			ja4Hash: ja4,
+			...(i % 2 === 0 && { userAgentHash: `ua${i % 100}` }),
+		};
+	}
+
+	// high specificity — full scope portal rules
+	return {
+		type: AccessPolicyType.Block,
+		description,
+		clientId: `client${i % 20}`,
+		ja4Hash: ja4,
+		userAgentHash: `ua${i % 100}`,
+		headersHash: `hh${i % 200}`,
+		countryCode: `C${i % 30}`,
+	};
+};
+
+// Deterministic request-scope generator. Every request populates the
+// full set of user-scope fields the rules use, so under strict-match
+// semantics rules whose populated fields are a subset of the request
+// scope can actually apply. Mirrors a fully-instrumented production
+// request (ja4 + UA + headers + country + asn all known).
+const buildBenchmarkRequest = (i: number) => {
+	return {
+		clientId: `client${i % 20}`,
+		scope: {
+			ja4Hash: `t13d_bench_${(i % 50).toString().padStart(3, "0")}`,
+			userAgentHash: `ua${i % 100}`,
+			headersHash: `hh${i % 200}`,
+			countryCode: `C${i % 30}`,
+			asn: 1000 + (i % 500),
+		},
+	};
+};
+
+const percentile = (sortedMs: number[], q: number): number => {
+	if (sortedMs.length === 0) return 0;
+	const idx = Math.min(
+		sortedMs.length - 1,
+		Math.floor((sortedMs.length - 1) * q),
+	);
+	const v = sortedMs[idx];
+	return v ?? 0;
+};
+
+describe("redisRulesReader ranked-path benchmark", () => {
+	let redisConnection: RedisConnection;
+	let redisClient: RedisClientType;
+	let reader: RedisRulesReader;
+
+	const mockLogger = new Proxy(
+		{},
+		{
+			get: () => () => {},
+		},
+	) as unknown as Logger;
+
+	// Track every key we insert so cleanup deletes only our rules,
+	// leaving any other test suite's data and the shared index intact.
+	const seededKeys: string[] = [];
+
+	beforeAll(async () => {
+		redisConnection = createTestRedisConnection();
+		redisClient = await setupRedisIndex(
+			redisConnection,
+			accessRulesRedisIndex,
+			mockLogger,
+		).getClient();
+		reader = new RedisRulesReader(redisClient, mockLogger);
+
+		// Seed RULE_COUNT rules in batches of 1000 — same chunk size the
+		// production writer uses, mirrors realistic insert behaviour.
+		const rules: AccessRule[] = [];
+		for (let i = 0; i < RULE_COUNT; i++) {
+			rules.push(buildBenchmarkRule(i));
+		}
+		await executeBatchesSequentially(
+			chunkIntoBatches(rules, 1000),
+			async (batch) => {
+				const multi = redisClient.multi();
+				for (const rule of batch) {
+					const key = getAccessRuleRedisKey(rule);
+					seededKeys.push(key);
+					multi.hSet(key, getRedisRuleValue(rule));
+				}
+				await multi.exec();
+			},
+		);
+
+		const indexInfo = await redisClient.ft.info(ACCESS_RULES_REDIS_INDEX_NAME);
+		// Description is unique per rule so every rule should land on
+		// its own key; allow a 10% margin for any incidental dedupe.
+		expect(indexInfo.num_docs).toBeGreaterThan(RULE_COUNT * 0.9);
+	}, 120_000);
+
+	afterAll(async () => {
+		// Delete only the keys this suite inserted; do not flushAll
+		// because we share the redis instance (and the index) with the
+		// other integration test file.
+		await executeBatchesSequentially(
+			chunkIntoBatches(seededKeys, 1000),
+			async (batch) => {
+				const multi = redisClient.multi();
+				for (const key of batch) {
+					multi.del(key);
+				}
+				await multi.exec();
+			},
+		);
+	});
+
+	test(`ranked findRules p50/p99 over ${QUERY_COUNT} queries against ${RULE_COUNT} rules`, async () => {
+		// warm up — first call pays for index page-in
+		await reader.findRules(
+			{
+				policyScope: { clientId: "warmup" },
+				policyScopeMatch: FilterScopeMatch.Greedy,
+				userScope: { ja4Hash: "warmup" },
+				userScopeMatch: FilterScopeMatch.Greedy,
+			},
+			true,
+		);
+
+		const samples: number[] = [];
+		for (let i = 0; i < QUERY_COUNT; i++) {
+			const { clientId, scope } = buildBenchmarkRequest(i);
+			const start = performance.now();
+			await reader.findRules(
+				{
+					policyScope: { clientId },
+					policyScopeMatch: FilterScopeMatch.Greedy,
+					userScope: scope,
+					userScopeMatch: FilterScopeMatch.Greedy,
+				},
+				true,
+			);
+			samples.push(performance.now() - start);
+		}
+
+		samples.sort((a, b) => a - b);
+		const p50 = percentile(samples, 0.5);
+		const p99 = percentile(samples, 0.99);
+		const avg = samples.reduce((a, b) => a + b, 0) / samples.length;
+
+		console.log(
+			`ranked findRules: avg=${avg.toFixed(2)}ms  p50=${p50.toFixed(2)}ms  p99=${p99.toFixed(2)}ms  n=${samples.length}`,
+		);
+
+		expect(p50).toBeLessThan(P50_LATENCY_MS);
+		expect(p99).toBeLessThan(P99_LATENCY_MS);
+	}, 120_000);
+
+	test("ranked findRules result size is bounded by SERVER_SIDE_RANK_TOP_N", async () => {
+		// Fully-populated request that should apply to many seeded rules
+		// — the new path must cap at SERVER_SIDE_RANK_TOP_N (20).
+		const { clientId, scope } = buildBenchmarkRequest(0);
+		const results = await reader.findRules(
+			{
+				policyScope: { clientId },
+				policyScopeMatch: FilterScopeMatch.Greedy,
+				userScope: scope,
+				userScopeMatch: FilterScopeMatch.Greedy,
+			},
+			true,
+		);
+		expect(results.length).toBeLessThanOrEqual(20);
+		expect(results.length).toBeGreaterThan(0);
+	}, 60_000);
+
+	test("HGETALL-free: ranked path returns full rules without per-rule fanout", async () => {
+		// The benefit of the ranked path in production is *not* raw
+		// localhost latency (the strict-match index walk is heavier
+		// than a greedy FT.SEARCH on a quiet box). It's that the
+		// ranked path returns full rule bodies inside the single
+		// FT.AGGREGATE reply, with no follow-up HGETALL fanout. In
+		// production each HGETALL costs ~0.5ms of network RTT over
+		// the Docker bridge, so cutting hundreds of round trips per
+		// request is the win that doesn't appear in a localhost
+		// timing test.
+		//
+		// This test stands in for that: confirm the ranked path
+		// produces fully-populated AccessRule objects from one
+		// aggregate call (no separate hash fetches needed).
+		const { clientId, scope } = buildBenchmarkRequest(0);
+		const ranked = await reader.findRules(
+			{
+				policyScope: { clientId },
+				policyScopeMatch: FilterScopeMatch.Greedy,
+				userScope: scope,
+				userScopeMatch: FilterScopeMatch.Greedy,
+			},
+			true,
+		);
+
+		expect(ranked.length).toBeGreaterThan(0);
+		// Every returned record must have the policy fields populated —
+		// proves the LOAD pipeline includes them rather than relying
+		// on a follow-up HGETALL.
+		for (const rule of ranked) {
+			expect(rule.type).toBeDefined();
+		}
+	}, 60_000);
+
+	test("ranked findRules returns rules in specificity-descending order", async () => {
+		// A request that matches the high-specificity bucket should
+		// surface the rule with the most populated fields first.
+		const { clientId, scope } = buildBenchmarkRequest(9);
+		const results = await reader.findRules(
+			{
+				policyScope: { clientId },
+				policyScopeMatch: FilterScopeMatch.Greedy,
+				userScope: scope,
+				userScopeMatch: FilterScopeMatch.Greedy,
+			},
+			true,
+		);
+
+		if (results.length === 0) return;
+		const top = results[0];
+		if (!top) return;
+
+		// The top rule must have at least as many populated user-scope
+		// fields as any other returned rule.
+		const countFields = (r: AccessRule): number =>
+			(r.userId ? 1 : 0) +
+			(r.ja4Hash ? 1 : 0) +
+			(r.headersHash ? 1 : 0) +
+			(r.userAgentHash ? 1 : 0) +
+			(r.headHash ? 1 : 0) +
+			(r.coords ? 1 : 0) +
+			(r.countryCode ? 1 : 0) +
+			(r.asn !== undefined ? 1 : 0) +
+			(r.clientId ? 1 : 0) +
+			(r.numericIp !== undefined || r.numericIpMaskMin !== undefined ? 1 : 0);
+
+		const topScore = countFields(top);
+		for (const r of results) {
+			expect(countFields(r)).toBeLessThanOrEqual(topScore);
+		}
+	}, 60_000);
+});