@serverkgg/bridge 0.1.1 → 0.1.3

package/src/runtime/bridgeRegistry.test.ts

@@ -1,12 +1,30 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { tmpdir } from "node:os";
-import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
+import {
+	BridgeAction,
+	BridgeKind,
+	type BridgeRow,
+	BridgeSetupStepKind,
+	type BridgeUnavailable,
+	type BridgeValues,
+	type LocalizedText,
+} from "../core";
 import type { BridgeDriver } from "../modules";
-import { BridgeLayout } from "../panel";
-import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
+import { BridgeControl, BridgeFormTarget, BridgeLayout } from "../panel";
+import {
+	BRIDGE_ACTIVITY_KEYS,
+	BRIDGE_TEXT_LENGTH_LIMIT,
+	type BridgeConfig,
+	BridgeConfirm,
+	BridgeEventName,
+} from "../protocol";
+import { bridgeAvailabilitySchema } from "../wire";
+import { type ActivityNormalizeOptions, createActivityReporter } from "./bridgeActivity";
 import { createContext } from "./bridgeContext";
 import { createEventRing } from "./bridgeEvents";
 import { log } from "./bridgeLog";
+import { secretFieldKeys } from "./bridgeRedaction";
+import { BridgeRefusalError } from "./bridgeRefusalError";
 import { createRegistry } from "./bridgeRegistry";
 import { createSupervisor } from "./bridgeSupervisor";
 
@@ -39,7 +57,7 @@ const baseDriver = (): BridgeDriver => ({
 	},
 });
 
-const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {}) => {
+const harnessFor = (driver: BridgeDriver, variables: Record<string, string> = {}) => {
 	const settings = {
 		...config(),
 		variables,
@@ -58,6 +76,19 @@ const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {
 
 	const ring = createEventRing(driver.events, supervisor);
 
+	const activity: ActivityNormalizeOptions = {
+		secretKeys: new Set(secretFieldKeys(driver)),
+		redact: (text) => text,
+		warn: log.warn,
+	};
+
+	const reporter = createActivityReporter({
+		...activity,
+		onEmit(event, payload) {
+			ring.emit(event, payload);
+		},
+	});
+
 	const context = createContext(settings, supervisor, {
 		onLog: log,
 		onEmit(event, payload) {
@@ -66,16 +97,26 @@ const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {
 		onSetup() {
 			return;
 		},
+		onActivity(entry) {
+			reporter.report(entry);
+		},
 		async onRestart() {
 			return;
 		},
 	});
 
-	return createRegistry(driver, context, supervisor, ring);
+	return {
+		registry: createRegistry(driver, context, supervisor, ring, activity),
+		ring,
+	};
+};
+
+const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {}) => {
+	return harnessFor(driver, variables).registry;
 };
 
 describe("actions modules", () => {
-	test("lists its action ids in the manifest", () => {
+	it("lists its action ids in the manifest", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -110,7 +151,7 @@ describe("actions modules", () => {
 		]);
 	});
 
-	test("hands the whole argument bag to the handler", async () => {
+	it("hands the whole argument bag to the handler", async () => {
 		const received: BridgeValues[] = [];
 
 		const registry = registryFor({
@@ -138,7 +179,7 @@ describe("actions modules", () => {
 		]);
 	});
 
-	test("refuses to run while the game is stopped", async () => {
+	it("refuses to run while the game is stopped", async () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -161,7 +202,7 @@ describe("actions modules", () => {
 		).rejects.toThrow('module "broadcast" needs the game to be running');
 	});
 
-	test("rejects a driver that reuses a read action id", () => {
+	it("rejects a driver that reuses a read action id", () => {
 		expect(() =>
 			registryFor({
 				...baseDriver(),
@@ -181,7 +222,7 @@ describe("actions modules", () => {
 });
 
 describe("manifest events", () => {
-	test("lists the log patterns and the names the driver raises itself", () => {
+	it("lists the log patterns and the names the driver raises itself", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			events: {
@@ -211,7 +252,7 @@ describe("manifest events", () => {
 		]);
 	});
 
-	test("stays on the log patterns when the driver raises nothing itself", () => {
+	it("stays on the log patterns when the driver raises nothing itself", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			events: {
@@ -232,7 +273,7 @@ describe("manifest events", () => {
 });
 
 describe("collection row actions", () => {
-	test("passes the row and the arguments without the row id", async () => {
+	it("passes the row and the arguments without the row id", async () => {
 		const seen: {
 			row: BridgeRow;
 			args: BridgeValues;
@@ -277,7 +318,7 @@ describe("collection row actions", () => {
 		]);
 	});
 
-	test("keeps listing the built-in actions beside the row actions", () => {
+	it("keeps listing the built-in actions beside the row actions", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -357,7 +398,7 @@ describe("offline row actions", () => {
 		},
 	});
 
-	test("hands an offline action the id alone when the row is not listed", async () => {
+	it("hands an offline action the id alone when the row is not listed", async () => {
 		const seen: BridgeRow[] = [];
 		const registry = registryFor(
 			rosterDriver(
@@ -378,7 +419,7 @@ describe("offline row actions", () => {
 		]);
 	});
 
-	test("still refuses an unlisted row for an action that is not offline", async () => {
+	it("still refuses an unlisted row for an action that is not offline", async () => {
 		const registry = registryFor(
 			rosterDriver(
 				false,
@@ -396,7 +437,7 @@ describe("offline row actions", () => {
 });
 
 describe("preview modules", () => {
-	test("lists the preview action in the manifest", () => {
+	it("lists the preview action in the manifest", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -425,7 +466,7 @@ describe("preview modules", () => {
 		]);
 	});
 
-	test("shows the module the pending values as variables and leaves the rest as they are stored", async () => {
+	it("shows the module the pending values as variables and leaves the rest as they are stored", async () => {
 		const seen: {
 			version: string | null;
 			count: string | null;
@@ -479,7 +520,7 @@ describe("preview modules", () => {
 		]);
 	});
 
-	test("returns what the module answers", async () => {
+	it("returns what the module answers", async () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -498,7 +539,7 @@ describe("preview modules", () => {
 			},
 		});
 
-		expect(await registry.invoke("transition", BridgeAction.Preview)).toEqual({
+		expect((await registry.invoke("transition", BridgeAction.Preview)).result).toEqual({
 			confirm: BridgeConfirm.Strong,
 			lines: [
 				{
@@ -509,7 +550,7 @@ describe("preview modules", () => {
 		});
 	});
 
-	test("refuses an action a preview module does not answer", async () => {
+	it("refuses an action a preview module does not answer", async () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -530,7 +571,7 @@ describe("preview modules", () => {
 });
 
 describe("detail modules", () => {
-	test("lists read and its own action ids in the manifest", () => {
+	it("lists read and its own action ids in the manifest", () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -555,12 +596,13 @@ describe("detail modules", () => {
 				actions: [
 					BridgeAction.Read,
 					"update",
+					BridgeAction.Availability,
 				],
 			},
 		]);
 	});
 
-	test("returns what read answers", async () => {
+	it("returns what read answers", async () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -582,13 +624,13 @@ describe("detail modules", () => {
 			},
 		});
 
-		expect(await registry.invoke("modpackStatus", BridgeAction.Read)).toMatchObject({
+		expect((await registry.invoke("modpackStatus", BridgeAction.Read)).result).toMatchObject({
 			id: "modrinth:abc",
 			title: "Better MC",
 		});
 	});
 
-	test("hands the argument bag to an action and returns its outcome", async () => {
+	it("hands the argument bag to an action and returns its outcome", async () => {
 		const received: BridgeValues[] = [];
 
 		const registry = registryFor({
@@ -613,9 +655,11 @@ describe("detail modules", () => {
 		});
 
 		expect(
-			await registry.invoke("modpackStatus", "update", {
-				id: "modrinth:abc",
-			}),
+			(
+				await registry.invoke("modpackStatus", "update", {
+					id: "modrinth:abc",
+				})
+			).result,
 		).toEqual({
 			variables: {
 				MODPACK: "modrinth:abc:v2",
@@ -629,7 +673,7 @@ describe("detail modules", () => {
 		]);
 	});
 
-	test("refuses an action named after a read", () => {
+	it("refuses an action named after a read", () => {
 		expect(() =>
 			registryFor({
 				...baseDriver(),
@@ -646,7 +690,7 @@ describe("detail modules", () => {
 		).toThrow('module "modpackStatus" declares action "read", which is reserved for reads');
 	});
 
-	test("refuses an action the module does not answer", async () => {
+	it("refuses an action the module does not answer", async () => {
 		const registry = registryFor({
 			...baseDriver(),
 			modules: {
@@ -664,7 +708,7 @@ describe("detail modules", () => {
 });
 
 describe("the setup singleton", () => {
-	test("rides the manifest as its own block and never joins the panel modules", () => {
+	it("rides the manifest as its own block and never joins the panel modules", () => {
 		const steps = [
 			{
 				kind: BridgeSetupStepKind.Driver as const,
@@ -692,13 +736,13 @@ describe("the setup singleton", () => {
 		expect(manifest.modules.some((module) => module.kind === BridgeKind.Setup)).toBe(false);
 	});
 
-	test("leaves the manifest block empty for a driver that declares no setup", () => {
+	it("leaves the manifest block empty for a driver that declares no setup", () => {
 		expect(registryFor(baseDriver()).manifest().setup).toBeNull();
 	});
 });
 
 describe("protected action dispatch", () => {
-	test("advertises protection and refuses old callers before touching files", async () => {
+	it("advertises protection and refuses old callers before touching files", async () => {
 		let calls = 0;
 		const registry = registryFor({
 			...baseDriver(),
@@ -724,7 +768,7 @@ describe("protected action dispatch", () => {
 		await registry.invoke("world", "replace", {}, "01993720-0000-7000-8000-000000000001");
 		expect(calls).toBe(1);
 	});
-	test("rejects protection metadata for unknown actions or running-only modules", () => {
+	it("rejects protection metadata for unknown actions or running-only modules", () => {
 		for (const module of [
 			{
 				kind: BridgeKind.Actions as const,
@@ -757,3 +801,1002 @@ describe("protected action dispatch", () => {
 		}
 	});
 });
+
+describe("activity", () => {
+	const granted = {
+		name: BridgeEventName.AccessGranted,
+		text: {
+			ar: "أضفت Steve للقائمة البيضاء",
+			en: "Added Steve to the whitelist",
+		},
+		subject: "Steve",
+	};
+
+	const whitelistDriver = (fail = false): BridgeDriver => ({
+		...baseDriver(),
+		modules: {
+			whitelist: {
+				kind: BridgeKind.Actions,
+				actions: {
+					add: async (context) => {
+						context.activity.report(granted);
+
+						if (fail) {
+							throw new Error("the whitelist file is read-only");
+						}
+					},
+				},
+			},
+		},
+	});
+
+	it("answers an invoke with its result and the entries the handler reported", async () => {
+		const { registry, ring } = harnessFor(whitelistDriver());
+
+		expect(await registry.invoke("whitelist", "add")).toEqual({
+			result: null,
+			activity: [
+				granted,
+			],
+		});
+		expect(ring.drain(0).events).toEqual([]);
+	});
+
+	it("answers an empty list when the handler reported nothing", async () => {
+		const { registry } = harnessFor({
+			...baseDriver(),
+			modules: {
+				gameplay: {
+					kind: BridgeKind.Actions,
+					actions: {
+						timeDay: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		expect(await registry.invoke("gameplay", "timeDay")).toEqual({
+			result: null,
+			activity: [],
+		});
+	});
+
+	it("sends what a failing handler reported to the events ring", async () => {
+		const { registry, ring } = harnessFor(whitelistDriver(true));
+
+		await expect(registry.invoke("whitelist", "add")).rejects.toThrow("read-only");
+
+		expect(ring.drain(0).events).toEqual([
+			{
+				seq: 1,
+				event: BridgeEventName.AccessGranted,
+				payload: {
+					[BRIDGE_ACTIVITY_KEYS.ar]: granted.text.ar,
+					[BRIDGE_ACTIVITY_KEYS.en]: granted.text.en,
+					[BRIDGE_ACTIVITY_KEYS.subject]: "Steve",
+				},
+			},
+		]);
+	});
+
+	describe("settings writes", () => {
+		const settingsDriver = (options: {
+			stored: BridgeValues;
+			read?: () => Promise<BridgeValues>;
+			report?: boolean;
+		}): BridgeDriver => ({
+			...baseDriver(),
+			panel: {
+				tabs: [
+					{
+						id: "settings",
+						title: {
+							ar: "الإعدادات",
+							en: "Settings",
+						},
+						sections: [
+							{
+								layout: BridgeLayout.Form,
+								id: "game",
+								target: BridgeFormTarget.Settings,
+								module: "gameSettings",
+								fields: [
+									{
+										key: "difficulty",
+										control: BridgeControl.Select,
+										label: {
+											ar: "الصعوبة",
+											en: "Difficulty",
+										},
+									},
+									{
+										key: "rconPassword",
+										control: BridgeControl.Secret,
+										label: {
+											ar: "كلمة سر RCON",
+											en: "RCON password",
+										},
+									},
+								],
+							},
+						],
+					},
+				],
+			},
+			modules: {
+				gameSettings: {
+					kind: BridgeKind.Settings,
+					read: options.read ?? (async () => options.stored),
+					write: async (context, values) => {
+						Object.assign(options.stored, values);
+
+						if (options.report) {
+							context.activity.report({
+								name: BridgeEventName.SettingsApplied,
+								text: {
+									ar: "تطبّقت الإعدادات",
+									en: "Settings applied",
+								},
+							});
+						}
+					},
+				},
+			},
+		});
+
+		it("reports the keys whose value changed when the handler reported nothing", async () => {
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {
+						difficulty: "easy",
+						maxPlayers: 10,
+						expRate: "1.000000",
+						pvp: "True",
+					},
+				}),
+			);
+
+			const { activity } = await registry.invoke("gameSettings", BridgeAction.Write, {
+				difficulty: "hard",
+				maxPlayers: "10",
+				expRate: 1,
+				pvp: true,
+			});
+
+			expect(activity).toEqual([
+				{
+					name: BridgeEventName.SettingsChanged,
+					text: {
+						ar: "تم تغيير الإعدادات",
+						en: "Changed the settings",
+					},
+					details: {
+						keys: "difficulty",
+						count: 1,
+					},
+				},
+			]);
+		});
+
+		it("finishes the write even when a stored value cannot be compared", async () => {
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {},
+					read: async () =>
+						({
+							difficulty: {
+								toString() {
+									throw new Error("not a scalar");
+								},
+							},
+						}) as unknown as BridgeValues,
+				}),
+			);
+
+			expect(
+				await registry.invoke("gameSettings", BridgeAction.Write, {
+					difficulty: "hard",
+				}),
+			).toEqual({
+				result: null,
+				activity: [],
+			});
+		});
+
+		it("reports nothing when no value changed", async () => {
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {
+						difficulty: "easy",
+					},
+				}),
+			);
+
+			expect(
+				(
+					await registry.invoke("gameSettings", BridgeAction.Write, {
+						difficulty: "easy",
+					})
+				).activity,
+			).toEqual([]);
+		});
+
+		it("keeps the handler's own entry instead of the default", async () => {
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {
+						difficulty: "easy",
+					},
+					report: true,
+				}),
+			);
+
+			const { activity } = await registry.invoke("gameSettings", BridgeAction.Write, {
+				difficulty: "hard",
+			});
+
+			expect(activity.map((entry) => entry.name)).toEqual([
+				BridgeEventName.SettingsApplied,
+			]);
+		});
+
+		it("reports every written key when the settings could not be read first", async () => {
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {},
+					read: async () => {
+						throw new Error("the rest api is not up yet");
+					},
+				}),
+			);
+
+			const { activity } = await registry.invoke("gameSettings", BridgeAction.Write, {
+				difficulty: "hard",
+				pvp: true,
+			});
+
+			expect(activity.at(0)?.details).toEqual({
+				keys: "difficulty,pvp",
+				count: 2,
+			});
+		});
+
+		it("never carries the value of a secret field", async () => {
+			const secret = "hunter22hunter22";
+
+			const { registry } = harnessFor(
+				settingsDriver({
+					stored: {
+						rconPassword: "old-password-1234",
+					},
+				}),
+			);
+
+			const { activity } = await registry.invoke("gameSettings", BridgeAction.Write, {
+				rconPassword: secret,
+			});
+
+			expect(activity.at(0)?.details).toEqual({
+				keys: "rconPassword",
+				count: 1,
+			});
+			expect(JSON.stringify(activity)).not.toContain(secret);
+		});
+
+		it("drops a detail a handler keyed by a secret field", async () => {
+			const { registry } = harnessFor({
+				...settingsDriver({
+					stored: {},
+				}),
+				modules: {
+					gameSettings: {
+						kind: BridgeKind.Settings,
+						read: async () => ({}),
+						write: async (context, values) => {
+							context.activity.report({
+								name: BridgeEventName.SecretRotated,
+								text: {
+									ar: "تغيّرت كلمة سر RCON",
+									en: "RCON password rotated",
+								},
+								details: {
+									rconPassword: String(values.rconPassword),
+								},
+							});
+						},
+					},
+				},
+			});
+
+			const { activity } = await registry.invoke("gameSettings", BridgeAction.Write, {
+				rconPassword: "hunter22hunter22",
+			});
+
+			expect(activity).toEqual([
+				{
+					name: BridgeEventName.SecretRotated,
+					text: {
+						ar: "تغيّرت كلمة سر RCON",
+						en: "RCON password rotated",
+					},
+				},
+			]);
+		});
+	});
+
+	it("reports no default for a catalog install", async () => {
+		const { registry } = harnessFor({
+			...baseDriver(),
+			modules: {
+				mods: {
+					kind: BridgeKind.Catalog,
+					search: async () => ({
+						hits: [],
+						total: 0,
+						providers: [],
+						categories: [],
+						sorts: [],
+					}),
+					installed: async () => [],
+					install: async (_context, id) => ({
+						id,
+						provider: null,
+						path: `mods/${id}.jar`,
+						title: id,
+						version: null,
+						sizeBytes: 0,
+						enabled: true,
+						gameVersion: null,
+						stale: false,
+						pageUrl: null,
+						icon: null,
+					}),
+					remove: async () => {
+						return;
+					},
+				},
+			},
+		});
+
+		expect(
+			(
+				await registry.invoke("mods", BridgeAction.Install, {
+					id: "sodium",
+				})
+			).activity,
+		).toEqual([]);
+	});
+});
+
+describe("availability", () => {
+	const activeWorld: LocalizedText = {
+		ar: "ما تقدر تحذف العالم الشغّال",
+		en: "You cannot delete the active world",
+	};
+
+	const alreadyActive: LocalizedText = {
+		ar: "هذا العالم شغّال من قبل",
+		en: "This world is already active",
+	};
+
+	const worldsDriver = (spies: { listed: number; deleted: string[]; hookThrows?: boolean }): BridgeDriver => ({
+		...baseDriver(),
+		modules: {
+			worlds: {
+				kind: BridgeKind.Collection,
+				list: async () => {
+					spies.listed += 1;
+
+					return [
+						{
+							id: "world",
+							active: true,
+						},
+						{
+							id: "old",
+							active: false,
+						},
+					];
+				},
+				actions: {
+					delete: async (_context, row) => {
+						spies.deleted.push(row.id);
+					},
+					activate: async () => {
+						return;
+					},
+				},
+				unavailable: async (_context, row): Promise<BridgeUnavailable> => {
+					if (spies.hookThrows) {
+						throw new Error("the level file could not be read");
+					}
+
+					return row.active === true
+						? {
+								delete: activeWorld,
+								activate: alreadyActive,
+							}
+						: {};
+				},
+			},
+		},
+	});
+
+	const refusalOf = async (promise: Promise<unknown>) => {
+		try {
+			await promise;
+		} catch (error) {
+			return error;
+		}
+
+		throw new Error("the invoke did not refuse");
+	};
+
+	it("advertises availability only for a collection that declares the hook", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+					actions: {
+						kick: async () => {
+							return;
+						},
+					},
+				},
+				worlds: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+					actions: {
+						delete: async () => {
+							return;
+						},
+					},
+					unavailable: async () => ({}),
+				},
+			},
+		});
+
+		expect(registry.manifest().modules.map((module) => module.actions)).toEqual([
+			[
+				BridgeAction.List,
+				"kick",
+			],
+			[
+				BridgeAction.List,
+				"delete",
+				BridgeAction.Availability,
+			],
+		]);
+	});
+
+	it("answers the reasons per row and leaves available rows out", async () => {
+		const registry = registryFor(
+			worldsDriver({
+				listed: 0,
+				deleted: [],
+			}),
+		);
+
+		expect((await registry.invoke("worlds", BridgeAction.Availability)).result).toEqual({
+			module: {},
+			subjects: {
+				world: {
+					delete: activeWorld,
+					activate: alreadyActive,
+				},
+			},
+		});
+	});
+
+	it("narrows the answer to one row when asked for its id", async () => {
+		const registry = registryFor(
+			worldsDriver({
+				listed: 0,
+				deleted: [],
+			}),
+		);
+
+		expect(
+			(
+				await registry.invoke("worlds", BridgeAction.Availability, {
+					id: "old",
+				})
+			).result,
+		).toEqual({
+			module: {},
+			subjects: {},
+		});
+	});
+
+	it("refuses an unavailable row action before the driver is entered", async () => {
+		const spies = {
+			listed: 0,
+			deleted: [] as string[],
+		};
+		const registry = registryFor(worldsDriver(spies));
+
+		const error = await refusalOf(
+			registry.invoke("worlds", "delete", {
+				id: "world",
+			}),
+		);
+
+		expect(error).toBeInstanceOf(BridgeRefusalError);
+		expect((error as BridgeRefusalError).text).toEqual(activeWorld);
+		expect(spies.deleted).toEqual([]);
+
+		await registry.invoke("worlds", "delete", {
+			id: "old",
+		});
+
+		expect(spies.deleted).toEqual([
+			"old",
+		]);
+	});
+
+	it("lets the action run when the hook itself fails", async () => {
+		const spies = {
+			listed: 0,
+			deleted: [] as string[],
+			hookThrows: true,
+		};
+		const registry = registryFor(worldsDriver(spies));
+
+		await registry.invoke("worlds", "delete", {
+			id: "world",
+		});
+
+		expect(spies.deleted).toEqual([
+			"world",
+		]);
+	});
+
+	it("lets an availability read join a list already in flight and never reuses a settled one", async () => {
+		const spies = {
+			listed: 0,
+			deleted: [] as string[],
+		};
+		const registry = registryFor(worldsDriver(spies));
+
+		await Promise.all([
+			registry.invoke("worlds", BridgeAction.List),
+			registry.invoke("worlds", BridgeAction.Availability),
+		]);
+
+		expect(spies.listed).toBe(1);
+
+		await registry.invoke("worlds", BridgeAction.Availability);
+		await registry.invoke("worlds", BridgeAction.List);
+
+		expect(spies.listed).toBe(3);
+	});
+
+	it("lists fresh for every list read and every action", async () => {
+		const spies = {
+			listed: 0,
+			deleted: [] as string[],
+		};
+		const registry = registryFor(worldsDriver(spies));
+
+		await Promise.all([
+			registry.invoke("worlds", BridgeAction.List),
+			registry.invoke("worlds", BridgeAction.List),
+		]);
+		await registry.invoke("worlds", "delete", {
+			id: "old",
+		});
+
+		expect(spies.listed).toBe(3);
+	});
+
+	it("forgets a list in flight when any module mutates", async () => {
+		let listed = 0;
+		let release = () => {};
+		const gate = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				worlds: {
+					kind: BridgeKind.Collection,
+					list: async () => {
+						listed += 1;
+
+						if (listed === 1) {
+							await gate;
+						}
+
+						return [];
+					},
+					actions: {
+						delete: async () => {
+							return;
+						},
+					},
+					unavailable: async () => ({}),
+				},
+				gameplay: {
+					kind: BridgeKind.Actions,
+					actions: {
+						activate: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		const first = registry.invoke("worlds", BridgeAction.List);
+
+		await Bun.sleep(0);
+		await registry.invoke("gameplay", "activate");
+		await registry.invoke("worlds", BridgeAction.Availability);
+
+		expect(listed).toBe(2);
+
+		release();
+		await first;
+	});
+
+	it("drops reasons for actions the module cannot refuse and clamps long ones", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				worlds: {
+					kind: BridgeKind.Collection,
+					list: async () => [
+						{
+							id: "world",
+						},
+					],
+					actions: {
+						delete: async () => {
+							return;
+						},
+					},
+					unavailable: async () => ({
+						list: activeWorld,
+						rename: activeWorld,
+						delete: {
+							ar: "ا".repeat(BRIDGE_TEXT_LENGTH_LIMIT + 20),
+							en: "a".repeat(BRIDGE_TEXT_LENGTH_LIMIT + 20),
+						},
+					}),
+				},
+			},
+		});
+
+		expect((await registry.invoke("worlds", BridgeAction.Availability)).result).toEqual({
+			module: {},
+			subjects: {
+				world: {
+					delete: {
+						ar: "ا".repeat(BRIDGE_TEXT_LENGTH_LIMIT),
+						en: "a".repeat(BRIDGE_TEXT_LENGTH_LIMIT),
+					},
+				},
+			},
+		});
+	});
+
+	it("drops entries the wire would refuse so the answer always validates", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				worlds: {
+					kind: BridgeKind.Collection,
+					list: async () => [
+						{
+							id: "",
+						},
+						{
+							id: "world",
+						},
+					],
+					actions: {
+						"not a key": async () => {
+							return;
+						},
+						delete: async () => {
+							return;
+						},
+					},
+					unavailable: async () => ({
+						"not a key": activeWorld,
+						delete: activeWorld,
+					}),
+				},
+			},
+		});
+
+		const { result } = await registry.invoke("worlds", BridgeAction.Availability);
+
+		expect(result).toEqual({
+			module: {},
+			subjects: {
+				world: {
+					delete: activeWorld,
+				},
+			},
+		});
+		expect(bridgeAvailabilitySchema.safeParse(result).success).toBe(true);
+	});
+
+	it("enforces the allow-list of a detail and answers its reasons", async () => {
+		const updates: BridgeValues[] = [];
+		let pressable: string[] = [];
+		const stale: LocalizedText = {
+			ar: "المود باك محدّث",
+			en: "The modpack is up to date",
+		};
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => ({
+						id: "modrinth:abc",
+						title: "Better MC",
+						subtitle: null,
+						description: null,
+						image: null,
+						badges: [],
+						stats: [],
+						links: [],
+						stale: false,
+						actions: pressable,
+						unavailable: {
+							update: stale,
+						},
+					}),
+					actions: {
+						update: async (_context, args) => {
+							updates.push(args);
+
+							return null;
+						},
+						repair: async () => null,
+					},
+				},
+			},
+		});
+
+		expect((await registry.invoke("modpackStatus", BridgeAction.Availability)).result).toEqual({
+			module: {
+				update: stale,
+				repair: {
+					ar: "هذا الإجراء غير متاح حاليًا",
+					en: "This action isn't available right now",
+				},
+			},
+			subjects: {},
+		});
+
+		const error = await refusalOf(registry.invoke("modpackStatus", "update"));
+
+		expect(error).toBeInstanceOf(BridgeRefusalError);
+		expect((error as BridgeRefusalError).text).toEqual(stale);
+		expect(updates).toEqual([]);
+
+		pressable = [
+			"update",
+		];
+
+		await registry.invoke("modpackStatus", "update");
+
+		expect(updates).toHaveLength(1);
+	});
+
+	it("refuses an actions module, a settings write and a catalog removal through their hooks", async () => {
+		const closed: LocalizedText = {
+			ar: "مقفل الحين",
+			en: "Closed right now",
+		};
+		const entered: string[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				gameplay: {
+					kind: BridgeKind.Actions,
+					actions: {
+						wipe: async () => {
+							entered.push("wipe");
+						},
+					},
+					unavailable: async () => ({
+						wipe: closed,
+					}),
+				},
+				gameSettings: {
+					kind: BridgeKind.Settings,
+					read: async () => ({}),
+					write: async () => {
+						entered.push("write");
+					},
+					unavailable: async () => ({
+						write: closed,
+					}),
+				},
+				mods: {
+					kind: BridgeKind.Catalog,
+					search: async () => ({
+						hits: [],
+						total: 0,
+						providers: [],
+						categories: [],
+						sorts: [],
+					}),
+					installed: async () => [
+						{
+							id: "jei",
+							provider: null,
+							path: "mods/jei.jar",
+							title: "JEI",
+							version: null,
+							sizeBytes: 1,
+							enabled: true,
+							gameVersion: null,
+							stale: false,
+							pageUrl: null,
+							icon: null,
+						},
+					],
+					install: async () => {
+						throw new Error("not in this test");
+					},
+					remove: async () => {
+						entered.push("remove");
+					},
+					unavailable: async () => ({
+						remove: closed,
+					}),
+				},
+			},
+		});
+
+		expect(registry.manifest().modules.map((module) => module.actions.includes(BridgeAction.Availability))).toEqual([
+			true,
+			true,
+			true,
+		]);
+
+		for (const [module, action, args] of [
+			[
+				"gameplay",
+				"wipe",
+				{},
+			],
+			[
+				"gameSettings",
+				BridgeAction.Write,
+				{
+					motd: "hi",
+				},
+			],
+			[
+				"mods",
+				BridgeAction.Remove,
+				{
+					id: "jei",
+				},
+			],
+		] as const) {
+			const error = await refusalOf(registry.invoke(module, action, args));
+
+			expect(error).toBeInstanceOf(BridgeRefusalError);
+			expect((error as BridgeRefusalError).text).toEqual(closed);
+		}
+
+		expect(entered).toEqual([]);
+
+		expect((await registry.invoke("mods", BridgeAction.Availability)).result).toEqual({
+			module: {},
+			subjects: {
+				jei: {
+					remove: closed,
+				},
+			},
+		});
+		expect((await registry.invoke("gameplay", BridgeAction.Availability)).result).toEqual({
+			module: {
+				wipe: closed,
+			},
+			subjects: {},
+		});
+	});
+
+	it("does not answer availability for a module that declares no hook", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+				},
+			},
+		});
+
+		await expect(registry.invoke("players", BridgeAction.Availability)).rejects.toThrow(
+			'module "players" does not support "availability"',
+		);
+	});
+
+	it("refuses a driver that names a row action availability", () => {
+		expect(() =>
+			registryFor({
+				...baseDriver(),
+				modules: {
+					worlds: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+						actions: {
+							availability: async () => {
+								return;
+							},
+						},
+					},
+				},
+			}),
+		).toThrow('module "worlds" declares action "availability", which is reserved for reads');
+	});
+
+	it("turns the gates that never enter the driver into refusals without text", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				gameplay: {
+					kind: BridgeKind.Actions,
+					requiresRunning: true,
+					actions: {
+						timeDay: async () => {
+							return;
+						},
+					},
+				},
+				world: {
+					kind: BridgeKind.Actions,
+					protectedActions: [
+						"replace",
+					],
+					actions: {
+						replace: async () => {
+							return;
+						},
+					},
+				},
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+					actions: {
+						kick: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		for (const invoke of [
+			registry.invoke("missing", "timeDay"),
+			registry.invoke("gameplay", "timeDay"),
+			registry.invoke("world", "replace"),
+			registry.invoke("players", "kick", {
+				id: "meslzy",
+			}),
+			registry.invoke("gameplay", "nightTime"),
+		]) {
+			const error = await refusalOf(invoke);
+
+			expect(error).toBeInstanceOf(BridgeRefusalError);
+			expect((error as BridgeRefusalError).text).toBeNull();
+		}
+	});
+});