cursedbelt-server 1.0.0

package/src/server/notifications/routes.ts

@@ -0,0 +1,177 @@
+/**
+ * The plain-HTTP surface for the notification center.
+ *
+ * ── Why this exists (2026-08-11) ────────────────────────────────────────────
+ * The engine (`cwip/notifications`), the store and the whole client
+ * (`cursedbelt/react/notifications`) were already fleet-wide. The only mounted
+ * SERVER surface was `orch-ui/services/notifications`, written against
+ * `@satellites/satellite-rpc` and living inside a package only the orchestrator
+ * consumes — so every other satellite's route to a notification was "adopt
+ * orch's rpc layer" or "write it again". This is that surface as ordinary
+ * routes on an ordinary Hono app, one mount call, no rpc.
+ *
+ * The route table mirrors the rpc one 1:1 on purpose: the two are the same
+ * contract in two dialects, and a client written against either sees the same
+ * fields. `mutations` are POST/DELETE and `queries` are GET, so the GET-only
+ * enforcement middleware some satellites run stays meaningful.
+ *
+ *   GET    {base}                → { items, hasMore }   ?filter=&limit=&offset=
+ *   GET    {base}/unread-count   → { count }
+ *   GET    {base}/stream         → SSE (live delivery; needs a hub)
+ *   GET    {base}/:id            → { notification }
+ *   POST   {base}/read-all       → { changed }
+ *   POST   {base}/done-all       → { changed }
+ *   POST   {base}/:id/read       → { changed }   body { read?: boolean }
+ *   POST   {base}/:id/done       → { changed }   body { done?: boolean }
+ *   DELETE {base}/:id            → { changed }
+ *
+ * 🔴 **Every handler addresses `authorize(c)`'s user and never a body field.**
+ * The center is user-scoped at the store level, but a route that took a
+ * `userId` parameter would make that scoping decorative — so there is no such
+ * parameter anywhere below, and there is deliberately no route that notifies
+ * somebody else. Producing notifications is server-side business logic calling
+ * `center.notify*` directly; a browser can only ever read and acknowledge its
+ * OWN inbox.
+ */
+import type { Context, Hono } from "hono";
+import type { NotificationCenter, NotificationFilter } from "cwip/notifications";
+import type { NotificationHub } from "./hub";
+
+/** The slice of the center these routes use — `createNotificationCenter(...)`
+ *  satisfies it, and so does any app-specific facade over one. */
+export type NotificationRouteCenter = Pick<
+	NotificationCenter,
+	"list" | "get" | "unreadCount" | "markRead" | "markAllRead" | "setDone" | "doneAll" | "remove"
+>;
+
+export interface NotificationRoutesOptions {
+	center: NotificationRouteCenter;
+	/**
+	 * Resolve the caller to a user id, or null to refuse with 401. This is the
+	 * app's session model and the ONLY thing that decides whose inbox is served.
+	 */
+	authorize: (c: Context) => string | null | Promise<string | null>;
+	/** Live delivery. Omit it and `{base}/stream` is not mounted at all — a
+	 *  route that answers 200 with a stream that never emits is worse than a
+	 *  404 the client can fall back from. */
+	hub?: NotificationHub;
+	/** Path prefix. Default `/api/notifications`. */
+	basePath?: string;
+	/** Largest page a caller may ask for. Default 200. */
+	maxLimit?: number;
+}
+
+const NO_STORE = { "cache-control": "no-store" } as const;
+
+const FILTERS: readonly NotificationFilter[] = ["unread", "all", "done"];
+
+const parseFilter = (raw: string | undefined): NotificationFilter | undefined =>
+	FILTERS.find((f) => f === raw);
+
+/** Query integers are untrusted text: a NaN or a negative offset must become
+ *  the default, never reach SQL, and never be an error the caller has to handle. */
+const parseInt_ = (raw: string | undefined, min: number, max: number): number | undefined => {
+	if (raw === undefined || raw === "") return undefined;
+	const value = Number.parseInt(raw, 10);
+	if (!Number.isFinite(value)) return undefined;
+	return Math.min(max, Math.max(min, value));
+};
+
+/** A body that is absent, malformed, or oversized is `{}` — every field these
+ *  routes read is optional with a documented default, so there is nothing a
+ *  caller could usefully be told about a bad one. */
+const readFlag = async (c: Context, key: "read" | "done"): Promise<boolean> => {
+	try {
+		const raw = await c.req.text();
+		if (!raw || raw.length > 1024) return true;
+		const body = JSON.parse(raw) as Record<string, unknown> | null;
+		const value = body?.[key];
+		return typeof value === "boolean" ? value : true;
+	} catch {
+		return true;
+	}
+};
+
+export function mountNotificationRoutes(app: Hono, options: NotificationRoutesOptions): void {
+	const base = options.basePath ?? "/api/notifications";
+	const maxLimit = options.maxLimit ?? 200;
+	const { center, hub } = options;
+
+	/** Every handler starts here. Returns the user id, or the 401 to return. */
+	const whoOr401 = async (c: Context): Promise<string | Response> => {
+		const userId = await options.authorize(c);
+		if (!userId) return c.json({ error: "unauthorized" }, 401, NO_STORE);
+		return userId;
+	};
+
+	app.get(base, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		const page = await center.list({
+			userId: who,
+			filter: parseFilter(c.req.query("filter")),
+			limit: parseInt_(c.req.query("limit"), 1, maxLimit),
+			offset: parseInt_(c.req.query("offset"), 0, Number.MAX_SAFE_INTEGER),
+		});
+		return c.json(page, 200, NO_STORE);
+	});
+
+	app.get(`${base}/unread-count`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		return c.json({ count: await center.unreadCount(who) }, 200, NO_STORE);
+	});
+
+	// Mounted only when there is something to stream — see the option's doc.
+	if (hub) {
+		app.get(`${base}/stream`, async (c) => {
+			const who = await whoOr401(c);
+			if (typeof who !== "string") return who;
+			// The request's own abort signal is what ends the stream when the tab
+			// closes; without it the subscription outlives the socket.
+			return hub.stream(who, { signal: c.req.raw.signal });
+		});
+	}
+
+	app.post(`${base}/read-all`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		return c.json({ changed: await center.markAllRead(who) }, 200, NO_STORE);
+	});
+
+	app.post(`${base}/done-all`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		return c.json({ changed: await center.doneAll(who) }, 200, NO_STORE);
+	});
+
+	app.post(`${base}/:id/read`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		const read = await readFlag(c, "read");
+		return c.json({ changed: await center.markRead(who, c.req.param("id"), read) }, 200, NO_STORE);
+	});
+
+	app.post(`${base}/:id/done`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		const done = await readFlag(c, "done");
+		return c.json({ changed: await center.setDone(who, c.req.param("id"), done) }, 200, NO_STORE);
+	});
+
+	app.delete(`${base}/:id`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		return c.json({ changed: await center.remove(who, c.req.param("id")) }, 200, NO_STORE);
+	});
+
+	// LAST: `/:id` would otherwise swallow `/unread-count` and `/stream`, and
+	// the failure is a 404-shaped `{ notification: null }` rather than an error.
+	app.get(`${base}/:id`, async (c) => {
+		const who = await whoOr401(c);
+		if (typeof who !== "string") return who;
+		const notification = await center.get(who, c.req.param("id"));
+		if (!notification) return c.json({ error: "not found" }, 404, NO_STORE);
+		return c.json({ notification }, 200, NO_STORE);
+	});
+}

package/src/server/notifications/service.spec.ts

@@ -0,0 +1,305 @@
+/**
+ * The server half end to end: a real SQLite database, a real Hono app, real
+ * HTTP requests through `app.fetch`.
+ *
+ * Every assertion here is about a property a consuming app depends on — the
+ * user scoping, the coalescing, the acknowledgment verbs, and the two that
+ * would be silent if they broke: that `/unread-count` is not swallowed by
+ * `/:id`, and that a stream ends when its request is aborted.
+ */
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { createNotificationHub } from "./hub";
+import { NOTIFICATION_MIGRATIONS, NOTIFICATIONS_TABLE } from "./migrations";
+import { createNotificationService, type NotificationService } from "./service";
+
+let db: Database;
+let service: NotificationService;
+let app: Hono;
+/** Whose session the next request carries. `null` = signed out. */
+let who: string | null;
+
+beforeEach(() => {
+	db = new Database(":memory:");
+	who = "u1";
+	service = createNotificationService({ db, live: { heartbeatMs: 0 }, onError: () => {} });
+	app = new Hono();
+	service.mount(app, { authorize: () => who });
+});
+
+afterEach(() => {
+	service.close();
+	db.close();
+});
+
+const get = (path: string) => app.fetch(new Request(`http://t${path}`));
+const post = (path: string, body?: unknown) =>
+	app.fetch(
+		new Request(`http://t${path}`, {
+			method: "POST",
+			...(body === undefined ? {} : { body: JSON.stringify(body) }),
+		}),
+	);
+const del = (path: string) => app.fetch(new Request(`http://t${path}`, { method: "DELETE" }));
+
+describe("the inbox surface", () => {
+	test("a notification is listed, counted, and carries its deep link", async () => {
+		await service.center.notify("u1", {
+			type: "auth.login",
+			title: "New sign-in",
+			body: "from 10.0.0.1",
+			link: "/#/account",
+			severity: "warning",
+		});
+
+		const page = await (await get("/api/notifications")).json();
+		expect(page.items).toHaveLength(1);
+		expect(page.items[0]).toMatchObject({
+			type: "auth.login",
+			title: "New sign-in",
+			link: "/#/account",
+			severity: "warning",
+			read: false,
+			count: 1,
+		});
+		expect(page.hasMore).toBe(false);
+		expect(await (await get("/api/notifications/unread-count")).json()).toEqual({ count: 1 });
+	});
+
+	test("🔴 one user never sees another's inbox", async () => {
+		await service.center.notify("u2", { type: "t", title: "not yours" });
+
+		expect((await (await get("/api/notifications")).json()).items).toEqual([]);
+		expect(await (await get("/api/notifications/unread-count")).json()).toEqual({ count: 0 });
+
+		// …and the id being guessable changes nothing.
+		const theirs = await service.center.notify("u2", { type: "t", title: "theirs" });
+		expect((await get(`/api/notifications/${theirs?.id}`)).status).toBe(404);
+		expect(await (await post(`/api/notifications/${theirs?.id}/read`)).json()).toEqual({
+			changed: false,
+		});
+		expect(await service.center.unreadCount("u2")).toBe(2);
+	});
+
+	test("🔴 signed out is 401 on every route, and no route leaks a body", async () => {
+		who = null;
+		for (const response of [
+			await get("/api/notifications"),
+			await get("/api/notifications/unread-count"),
+			await get("/api/notifications/anything"),
+			await get("/api/notifications/stream"),
+			await post("/api/notifications/read-all"),
+			await post("/api/notifications/done-all"),
+			await post("/api/notifications/x/read"),
+			await post("/api/notifications/x/done"),
+			await del("/api/notifications/x"),
+		]) {
+			expect(response.status).toBe(401);
+			expect(await response.json()).toEqual({ error: "unauthorized" });
+		}
+	});
+
+	test("🔴 /unread-count and /stream are routes, not ids", async () => {
+		// Registration order is the whole property: `/:id` is mounted last, so a
+		// static segment can never be read as a notification id.
+		expect((await get("/api/notifications/unread-count")).status).toBe(200);
+		expect((await get("/api/notifications/stream")).headers.get("content-type")).toContain(
+			"text/event-stream",
+		);
+	});
+
+	test("repeat events with a groupKey coalesce into one counted row", async () => {
+		for (let i = 0; i < 5; i++) {
+			await service.center.notify("u1", {
+				type: "auth.login",
+				title: `sign-in ${i}`,
+				groupKey: "auth.login",
+			});
+		}
+		const page = await (await get("/api/notifications")).json();
+		expect(page.items).toHaveLength(1);
+		expect(page.items[0].count).toBe(5);
+		// The newest event wins the row's copy — the count says how many.
+		expect(page.items[0].title).toBe("sign-in 4");
+		expect(await (await get("/api/notifications/unread-count")).json()).toEqual({ count: 1 });
+	});
+
+	test("acknowledging: read, read-all, done, done-all, remove", async () => {
+		const a = await service.center.notify("u1", { type: "t", title: "a" });
+		const b = await service.center.notify("u1", { type: "t", title: "b" });
+
+		expect(await (await post(`/api/notifications/${a?.id}/read`)).json()).toEqual({
+			changed: true,
+		});
+		expect(await (await get("/api/notifications/unread-count")).json()).toEqual({ count: 1 });
+
+		// …and the flag is honored, not assumed.
+		expect(
+			await (await post(`/api/notifications/${a?.id}/read`, { read: false })).json(),
+		).toEqual({ changed: true });
+		expect(await (await get("/api/notifications/unread-count")).json()).toEqual({ count: 2 });
+
+		expect(await (await post("/api/notifications/read-all")).json()).toEqual({ changed: 2 });
+
+		expect(await (await post(`/api/notifications/${b?.id}/done`)).json()).toEqual({
+			changed: true,
+		});
+		let page = await (await get("/api/notifications")).json();
+		expect(page.items.map((n: { id: string }) => n.id)).toEqual([a?.id]);
+		page = await (await get("/api/notifications?filter=done")).json();
+		expect(page.items.map((n: { id: string }) => n.id)).toEqual([b?.id]);
+
+		expect(await (await del(`/api/notifications/${a?.id}`)).json()).toEqual({ changed: true });
+		expect(await (await post("/api/notifications/done-all")).json()).toEqual({ changed: 0 });
+		expect((await (await get("/api/notifications")).json()).items).toEqual([]);
+	});
+
+	test("a malformed or oversized body falls back to the documented default", async () => {
+		const n = await service.center.notify("u1", { type: "t", title: "a" });
+		const response = await app.fetch(
+			new Request(`http://t/api/notifications/${n?.id}/read`, {
+				method: "POST",
+				body: "{not json",
+			}),
+		);
+		// Default is `read: true` — a bad body must not become a 500 or a no-op.
+		expect(await response.json()).toEqual({ changed: true });
+		expect(await service.center.unreadCount("u1")).toBe(0);
+	});
+
+	test("limit and offset are clamped, and junk becomes the default", async () => {
+		for (let i = 0; i < 4; i++) await service.center.notify("u1", { type: "t", title: `n${i}` });
+
+		expect((await (await get("/api/notifications?limit=2")).json()).hasMore).toBe(true);
+		expect((await (await get("/api/notifications?limit=2&offset=2")).json()).items).toHaveLength(2);
+		// max 200 by default; a bigger ask is clamped rather than refused
+		expect((await (await get("/api/notifications?limit=99999")).json()).items).toHaveLength(4);
+		// …and unparseable values must not reach SQL
+		expect((await (await get("/api/notifications?limit=abc&offset=-9")).json()).items).toHaveLength(
+			4,
+		);
+		expect((await (await get("/api/notifications?filter=nonsense")).json()).items).toHaveLength(4);
+	});
+});
+
+describe("live delivery", () => {
+	test("the sink reaches exactly the addressed user's subscribers", async () => {
+		const mine: string[] = [];
+		const theirs: string[] = [];
+		const hub = service.hub;
+		if (!hub) throw new Error("expected a hub");
+		hub.subscribe("u1", (e) => mine.push(e.kind));
+		hub.subscribe("u2", (e) => theirs.push(e.kind));
+
+		await service.center.notify("u1", { type: "t", title: "a" });
+
+		expect(mine).toEqual(["notification", "unread"]);
+		expect(theirs).toEqual([]);
+	});
+
+	test("🔴 an aborted request unsubscribes — a closed tab is not a leak", async () => {
+		const hub = service.hub;
+		if (!hub) throw new Error("expected a hub");
+		const controller = new AbortController();
+		const response = await app.fetch(
+			new Request("http://t/api/notifications/stream", { signal: controller.signal }),
+		);
+		const reader = response.body?.getReader();
+		// The opening comment line proves the stream is genuinely open.
+		expect(new TextDecoder().decode((await reader?.read())?.value)).toBe(": connected\n\n");
+		expect(hub.subscriberCount("u1")).toBe(1);
+
+		controller.abort();
+		await Promise.resolve();
+		expect(hub.subscriberCount("u1")).toBe(0);
+		await reader?.cancel().catch(() => {});
+	});
+
+	test("a notification arrives on an open stream as an SSE event", async () => {
+		const response = await get("/api/notifications/stream");
+		const reader = response.body?.getReader();
+		await reader?.read(); // ": connected"
+
+		await service.center.notify("u1", { type: "t", title: "hello", link: "/#/x" });
+
+		const frame = new TextDecoder().decode((await reader?.read())?.value);
+		expect(frame.startsWith("event: notification\ndata: ")).toBe(true);
+		expect(JSON.parse(frame.slice("event: notification\ndata: ".length))).toMatchObject({
+			title: "hello",
+			link: "/#/x",
+			userId: "u1",
+		});
+		await reader?.cancel().catch(() => {});
+	});
+
+	test("live: false mounts no stream route at all", async () => {
+		const plain = createNotificationService({ db, live: false });
+		const plainApp = new Hono();
+		plain.mount(plainApp, { authorize: () => "u1" });
+		const response = await plainApp.fetch(new Request("http://t/api/notifications/stream"));
+		// Falls through to `/:id` → a notification that does not exist.
+		expect(response.status).toBe(404);
+		expect(plain.hub).toBeNull();
+	});
+
+	test("a user's streams are capped, oldest first", () => {
+		const hub = createNotificationHub({ heartbeatMs: 0, maxStreamsPerUser: 2 });
+		const seen: number[] = [];
+		hub.subscribe("u1", () => seen.push(1));
+		hub.subscribe("u1", () => seen.push(2));
+		hub.subscribe("u1", () => seen.push(3));
+		expect(hub.subscriberCount("u1")).toBe(2);
+		// The evicted subscriber is the one that was there first.
+		expect(seen).toEqual([1]);
+		hub.close();
+	});
+
+	test("a throwing subscriber is dropped, and the next one still hears it", () => {
+		const hub = createNotificationHub({ heartbeatMs: 0, onError: () => {} });
+		const heard: string[] = [];
+		hub.subscribe("u1", () => {
+			throw new Error("boom");
+		});
+		hub.subscribe("u1", () => heard.push("ok"));
+		hub.sink.onUnread?.("u1", 3);
+		expect(heard).toEqual(["ok"]);
+		expect(hub.subscriberCount("u1")).toBe(1);
+		hub.close();
+	});
+});
+
+describe("the table", () => {
+	test("the migration and the store converge on one table, in either order", () => {
+		const fresh = new Database(":memory:");
+		for (const migration of NOTIFICATION_MIGRATIONS) migration.up(fresh);
+		// Constructing the store over an already-migrated database must not throw
+		// — an app that adopted the store first and the runner second is normal.
+		const second = createNotificationService({ db: fresh, live: false });
+		const columns = (
+			fresh.query(`PRAGMA table_info(${NOTIFICATIONS_TABLE})`).all() as { name: string }[]
+		).map((c) => c.name);
+		expect(columns).toContain("group_key");
+		expect(columns).toContain("severity");
+		second.close();
+		fresh.close();
+	});
+
+	test("🔴 coalescing is enforced by the index, not only by the read", () => {
+		// Two open rows in one group would make `count` a lie the moment two
+		// producers raced. The partial unique index is what forbids it.
+		const fresh = new Database(":memory:");
+		const svc = createNotificationService({ db: fresh, live: false });
+		const insert = () =>
+			fresh.run(
+				`INSERT INTO ${NOTIFICATIONS_TABLE}
+				 (id, user_id, created_at, updated_at, type, severity, title, group_key, count, read, done)
+				 VALUES (?, 'u1', 0, 0, 't', 'info', 'x', 'g', 1, 0, 0)`,
+				[crypto.randomUUID()],
+			);
+		insert();
+		expect(insert).toThrow();
+		svc.close();
+		fresh.close();
+	});
+});

package/src/server/notifications/service.ts

@@ -0,0 +1,112 @@
+/**
+ * One call that gives an app the whole server half: a migrated table, the
+ * dispatch center, live delivery, and the routes.
+ *
+ *   const notifications = createNotificationService({ db });
+ *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
+ *   // …anywhere in the app's business logic:
+ *   await notifications.center.notify(userId, { type: "auth.login", title: "New sign-in" });
+ *
+ * Everything it composes is separately usable — an app that already has a
+ * center, or that wants the routes on a store of its own, calls
+ * `mountNotificationRoutes` directly. This exists so the common case is one
+ * import and no wiring to get wrong.
+ */
+import type { Database } from "bun:sqlite";
+import {
+	createNotificationCenter,
+	createSqliteNotificationStore,
+	type NotificationCenter,
+	type NotificationDb,
+	type NotificationStore,
+} from "cwip/notifications";
+import type { Context, Hono } from "hono";
+import { createNotificationHub, type NotificationHub } from "./hub";
+import { mountNotificationRoutes } from "./routes";
+
+export interface CreateNotificationServiceOptions {
+	/** The app's own database — the table lands beside its rows. */
+	db: Database;
+	/** Table name override (identifier-validated by the store). */
+	table?: string;
+	/** Resolve a role audience (`notifyAudience({ role })`) to user ids. */
+	resolveRole?: (role: string) => Promise<string[]>;
+	/**
+	 * Live delivery. `false` builds no hub — the client's poll transport is the
+	 * whole delivery story then, which is a perfectly good one for an app whose
+	 * notifications are not time-critical.
+	 */
+	live?: boolean | { heartbeatMs?: number; maxStreamsPerUser?: number };
+	/** Producer-path failures and sink failures land here. Defaults to stderr. */
+	onError?: (error: unknown, context: string) => void;
+	/** Test seams, forwarded to the center. */
+	now?: () => number;
+	newId?: () => string;
+}
+
+export interface NotificationServiceMountOptions {
+	/** Resolve the caller to a user id, or null to refuse. */
+	authorize: (c: Context) => string | null | Promise<string | null>;
+	/** Path prefix. Default `/api/notifications`. */
+	basePath?: string;
+	/** Largest page a caller may ask for. Default 200. */
+	maxLimit?: number;
+}
+
+export interface NotificationService {
+	readonly center: NotificationCenter;
+	readonly store: NotificationStore;
+	/** Null when `live: false` — there is then nothing to stream. */
+	readonly hub: NotificationHub | null;
+	mount(app: Hono, options: NotificationServiceMountOptions): void;
+	/** Drop live subscribers (shutdown, tests). Safe to call with no hub. */
+	close(): void;
+}
+
+export function createNotificationService(
+	options: CreateNotificationServiceOptions,
+): NotificationService {
+	const onError =
+		options.onError ??
+		((error: unknown, context: string) =>
+			console.error(`[notifications] ${context}:`, error instanceof Error ? error.message : error));
+
+	const store = createSqliteNotificationStore(options.db as unknown as NotificationDb, {
+		table: options.table,
+	});
+
+	const hub =
+		options.live === false
+			? null
+			: createNotificationHub({
+					...(typeof options.live === "object" ? options.live : {}),
+					onError,
+				});
+
+	const center = createNotificationCenter({
+		store,
+		sink: hub?.sink,
+		resolveRole: options.resolveRole,
+		now: options.now,
+		newId: options.newId,
+		onError,
+	});
+
+	return {
+		center,
+		store,
+		hub,
+		mount(app, mountOptions) {
+			mountNotificationRoutes(app, {
+				center,
+				hub: hub ?? undefined,
+				authorize: mountOptions.authorize,
+				basePath: mountOptions.basePath,
+				maxLimit: mountOptions.maxLimit,
+			});
+		},
+		close() {
+			hub?.close();
+		},
+	};
+}

package/src/server/paths/appDataHome.spec.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "bun:test";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome, XDG_DATA_HOME_ENV } from "./appDataHome";
+
+/**
+ * The published-library defect this file is the gate for: a resolver that knows
+ * the name of a directory in one person's home. Every assertion below is either
+ * "the caller decides" or "the OS decides"; there is no third source.
+ */
+describe("the app-data home", () => {
+	it("takes an explicit argument over everything else", () => {
+		expect(
+			resolveAppDataHome({
+				override: "/srv/data",
+				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
+			}),
+		).toBe("/srv/data");
+	});
+
+	it("reads APP_DATA_HOME — the one env var — before any convention", () => {
+		expect(
+			resolveAppDataHome({
+				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
+			}),
+		).toBe("/env/data");
+	});
+
+	it("honors XDG_DATA_HOME on every platform, macOS included", () => {
+		for (const platform of ["darwin", "linux"]) {
+			expect(resolveAppDataHome({ env: { [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" }, platform })).toBe("/xdg");
+		}
+	});
+
+	it("falls back to the macOS convention, not to anybody's dotfolder", () => {
+		const resolved = resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "darwin" });
+		expect(resolved).toBe(join("/home/x", "Library", "Application Support"));
+	});
+
+	it("falls back to the XDG default path elsewhere", () => {
+		expect(resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "linux" })).toBe(
+			join("/home/x", ".local", "share"),
+		);
+	});
+
+	// Whitespace is how an env var gets "set" by a shell script that meant to unset
+	// it; treating it as configuration points every app at the filesystem root.
+	it("treats a blank setting as no setting", () => {
+		expect(
+			resolveAppDataHome({
+				override: "  ",
+				env: { [APP_DATA_HOME_ENV]: " ", [XDG_DATA_HOME_ENV]: "", HOME: "/home/x" },
+				platform: "linux",
+			}),
+		).toBe(join("/home/x", ".local", "share"));
+	});
+
+	it("falls back to the process's own home when the env names none", () => {
+		expect(resolveAppDataHome({ env: {}, platform: "linux" })).toBe(join(homedir(), ".local", "share"));
+	});
+
+	/**
+	 * 🔴 The assertion this module exists for. It is deliberately a property of the
+	 * OUTPUT rather than of the source text, so it still holds if somebody
+	 * reintroduces the old folder through a variable, a `join`, or a constant.
+	 */
+	it("never resolves a previous generation's private directory", () => {
+		const envs: Array<Record<string, string | undefined>> = [
+			{},
+			{ HOME: "/home/x" },
+			{ HOME: "/home/x", [APP_DATA_HOME_ENV]: "/srv/data" },
+			{ HOME: "/home/x", [XDG_DATA_HOME_ENV]: "/xdg" },
+			// The previous generation's own env var must no longer steer anything: the
+			// value below is deliberately unlike any convention, so a resolver that
+			// still read this var could not produce a passing answer by accident.
+			{ HOME: "/home/x", APP_MANAGED_HOME: "/nowhere/inherited" },
+		];
+		for (const env of envs) {
+			for (const platform of ["darwin", "linux"]) {
+				const resolved = resolveAppDataHome({ env, platform });
+				expect(resolved).not.toContain("app-managed");
+				expect(resolved).not.toContain("code-retiring");
+				expect(resolved).not.toContain("Master-Docs");
+			}
+		}
+	});
+});