emdash 1.2.0 → 1.3.1

package/src/settings/index.ts

@@ -24,6 +24,9 @@ import {
 } from "../plugins/settings.js";
 import type { CacheHint } from "../query.js";
 import { peekRequestCache, requestCached } from "../request-cache.js";
+import { getRequestContext } from "../request-context.js";
+import { bumpRunningExportWriteEpochs } from "../transfer/fence.js";
+import { isMissingTableError } from "../utils/db-errors.js";
 
 /** Object-cache namespace for site settings. */
 const SETTINGS_CACHE_NAMESPACE = "settings";
@@ -41,6 +44,7 @@ import type {
 	SiteSettingsUpdate,
 	SiteSettingKey,
 } from "./types.js";
+import { normalizeSiteSettingsVersion } from "./version.js";
 
 /** Prefix for site settings in the options table */
 const SETTINGS_PREFIX = "site:";
@@ -80,10 +84,8 @@ async function decodePersistedPluginSetting(
  * Worker-isolate cache for the resolved `site:*` settings.
  *
  * Site settings (title, logo, SEO defaults) change rarely but are read on
- * every public request. Caching across the isolate's lifetime drops the
- * `options WHERE name LIKE 'site:%'` prefix scan from once-per-request to
- * once-per-isolate. Cross-isolate staleness is bounded by isolate lifetime
- * (workerd typically recycles within minutes); acceptable for chrome.
+ * every public request. Revalidate warm snapshots after 30 seconds in the
+ * background, retaining the last good value if the reload fails.
  *
  * Backed by single-flight-cache.ts: concurrent cold reads coalesce onto one
  * query via a reclaimable single-flight lock and the resolved *value* is
@@ -92,26 +94,60 @@ async function decodePersistedPluginSetting(
  * Symbol.for key so Vite SSR chunk duplication doesn't produce two
  * independent caches (same pattern as request-context.ts).
  */
-const SITE_SETTINGS_CACHE_KEY = Symbol.for("emdash:site-settings");
+interface CachedSiteSettings {
+	data: Partial<SiteSettings>;
+	version: string;
+}
+
+interface SiteSettingsCache {
+	snapshot: CachedSiteSettings | null;
+	expiresAt: number;
+	generation: number;
+	revalidatingUntil: number;
+	refresh: SingleFlightCache<CachedSiteSettings>;
+}
+
+const SITE_SETTINGS_CACHE_TTL_MS = 30_000;
+const SITE_SETTINGS_CACHE_KEY = Symbol.for("emdash:site-settings:swr");
 const g = globalThis as Record<symbol, unknown>;
-const settingsCache: SingleFlightCache<Partial<SiteSettings>> =
+const settingsCache: SiteSettingsCache =
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
-	(g[SITE_SETTINGS_CACHE_KEY] as SingleFlightCache<Partial<SiteSettings>> | undefined) ??
+	(g[SITE_SETTINGS_CACHE_KEY] as SiteSettingsCache | undefined) ??
 	(() => {
-		const c = createSingleFlightCache<Partial<SiteSettings>>();
+		const c: SiteSettingsCache = {
+			snapshot: null,
+			expiresAt: 0,
+			generation: 0,
+			revalidatingUntil: 0,
+			refresh: createSingleFlightCache<CachedSiteSettings>(),
+		};
 		g[SITE_SETTINGS_CACHE_KEY] = c;
 		return c;
 	})();
 
+/** Capture the resolved snapshot before route-cache headers are finalized. @internal */
+export function peekSiteSettingsSnapshot(): CachedSiteSettings | null {
+	return settingsCache.snapshot;
+}
+
+/** Discard a snapshot found stale by the route-cache freshness check. @internal */
+export function invalidateSiteSettingsSnapshot(): void {
+	settingsCache.generation++;
+	settingsCache.snapshot = null;
+	settingsCache.expiresAt = 0;
+	settingsCache.revalidatingUntil = 0;
+	invalidateSingleFlightCache(settingsCache.refresh);
+}
+
 /**
  * Bump the isolate-wide site-settings cache version, forcing the next
  * `getSiteSettings()` to re-query the database.
  *
  * Called from every `site:*` write path. Other isolates still serve their
- * own cached copy until they expire — staleness bounded by isolate lifetime.
+ * own cached copy while a background refresh picks up remote writes.
  */
 export function invalidateSiteSettingsCache(): void {
-	invalidateSingleFlightCache(settingsCache);
+	invalidateSiteSettingsSnapshot();
 	// Cross-isolate invalidation for the optional distributed object cache.
 	invalidateObjectCache(SETTINGS_CACHE_NAMESPACE);
 }
@@ -245,6 +281,58 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
 	return value;
 }
 
+function refreshSiteSettings(): Promise<CachedSiteSettings> {
+	return singleFlightCached(
+		settingsCache.refresh,
+		() =>
+			cachedQuery({
+				namespace: SETTINGS_CACHE_NAMESPACE,
+				key: "snapshot-v1",
+				load: async () => loadSiteSettingsSnapshot(await getDb()),
+			}),
+		{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
+	);
+}
+
+function installSiteSettings(snapshot: CachedSiteSettings): void {
+	settingsCache.snapshot = snapshot;
+	settingsCache.expiresAt = Date.now() + SITE_SETTINGS_CACHE_TTL_MS;
+}
+
+function revalidateSiteSettings(): void {
+	const now = Date.now();
+	if (settingsCache.revalidatingUntil > now) return;
+	settingsCache.revalidatingUntil = now + SITE_SETTINGS_CACHE_TTL_MS;
+	const generation = ++settingsCache.generation;
+	invalidateSingleFlightCache(settingsCache.refresh);
+	after(async () => {
+		try {
+			const snapshot = await refreshSiteSettings();
+			if (generation === settingsCache.generation) installSiteSettings(snapshot);
+		} catch (error) {
+			console.error("[emdash:settings] revalidating site settings failed:", error);
+		}
+	});
+}
+
+async function loadCachedSiteSettings(): Promise<CachedSiteSettings> {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const snapshot = settingsCache.snapshot;
+		if (snapshot) {
+			if (Date.now() >= settingsCache.expiresAt) revalidateSiteSettings();
+			return snapshot;
+		}
+		const generation = settingsCache.generation;
+		const loaded = await refreshSiteSettings();
+		if (generation === settingsCache.generation) {
+			installSiteSettings(loaded);
+			return loaded;
+		}
+		if (attempt === 2) return loaded;
+	}
+	throw new Error("Site settings refresh exhausted without loading settings");
+}
+
 /**
  * Get all site settings
  *
@@ -261,26 +349,28 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
  * ```
  */
 export function getSiteSettings(): Promise<Partial<SiteSettings>> {
-	// requestCached dedupes within a single request; singleFlightCached
-	// coalesces across requests and caches the resolved value for the
-	// global scope's lifetime without ever sharing an awaitable promise. The
-	// distributed object cache (cachedQuery) sits beneath both, backing cold
-	// isolates without a database round-trip.
-	return requestCached("siteSettings", () =>
-		singleFlightCached(
-			settingsCache,
-			() =>
-				cachedQuery({
-					namespace: SETTINGS_CACHE_NAMESPACE,
-					key: "all",
-					load: async () => {
-						const db = await getDb();
-						return getSiteSettingsWithDb(db);
-					},
-				}),
-			{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
-		),
-	);
+	return requestCached("siteSettings", async () => {
+		const snapshot = await requestCached("siteSettingsSnapshot", async () => {
+			const ctx = getRequestContext();
+			const requestSettings = ctx?.siteSettings;
+			if (ctx?.routeCacheFill) return loadSiteSettingsSnapshot(await getDb());
+			let loaded = requestSettings?.snapshot ?? (await loadCachedSiteSettings());
+			// A cold streamed component may join a load started before verification.
+			// Reload an older result instead of streaming that snapshot into a fill.
+			if (requestSettings?.version !== undefined && loaded.version !== requestSettings.version) {
+				invalidateSiteSettingsSnapshot();
+				const generation = settingsCache.generation;
+				loaded = await loadSiteSettingsSnapshot(await getDb());
+				if (generation === settingsCache.generation) installSiteSettings(loaded);
+			}
+			return loaded;
+		});
+		return snapshot.data;
+	}).then(async (data) => {
+		const snapshot = await peekRequestCache<CachedSiteSettings>("siteSettingsSnapshot");
+		if (snapshot) getRequestContext()?.siteSettings?.onRead(snapshot.version);
+		return data;
+	});
 }
 
 /**
@@ -307,15 +397,27 @@ export async function getSiteSettingsWithDb(
 	db: Kysely<Database>,
 	storage: Storage | null = null,
 ): Promise<Partial<SiteSettings>> {
-	const options = new OptionsRepository(db);
-	const allOptions = await options.getByPrefix(SETTINGS_PREFIX);
+	return (await loadSiteSettingsSnapshot(db, storage)).data;
+}
 
+async function loadSiteSettingsSnapshot(
+	db: Kysely<Database>,
+	storage: Storage | null = null,
+): Promise<CachedSiteSettings> {
+	const options = new OptionsRepository(db);
+	const allOptions = await options.getVersionedByPrefix(SETTINGS_PREFIX);
+	const version = normalizeSiteSettingsVersion(
+		JSON.stringify(
+			[...allOptions]
+				.filter(([key]) => key.startsWith(SETTINGS_PREFIX))
+				.map(([key, value]) => [key, value.revision]),
+		),
+	);
 	const settings: Record<string, unknown> = {};
 
-	// Convert Map to settings object, removing the prefix
 	for (const [key, value] of allOptions) {
 		const settingKey = key.replace(SETTINGS_PREFIX, "");
-		settings[settingKey] = value;
+		settings[settingKey] = value.value;
 	}
 
 	const typedSettings = settings as Partial<SiteSettings>;
@@ -334,7 +436,7 @@ export async function getSiteSettingsWithDb(
 		};
 	}
 
-	return typedSettings;
+	return { data: typedSettings, version };
 }
 
 /**
@@ -375,6 +477,10 @@ export async function setSiteSettings(
 		else updates[`${SETTINGS_PREFIX}${key}`] = value;
 	}
 
+	if (Object.keys(updates).length === 0 && deletions.length === 0 && nestedPatches.length === 0) {
+		return;
+	}
+
 	try {
 		await withTransaction(db, async (trx) => {
 			const transactionOptions = new OptionsRepository(trx);
@@ -391,6 +497,20 @@ export async function setSiteSettings(
 				if (Object.keys(next).length === 0) await transactionOptions.delete(optionName);
 				else await transactionOptions.set(optionName, next);
 			}
+
+			// A running export detects writes to tables without updated_at via
+			// the operation's write_epoch. Record that bump in the same
+			// transaction so the settings update is not accepted unless the
+			// export fence can see it. When the transfer system has not been
+			// installed yet (pre-migration, or a minimal seed fixture), there
+			// is no running export to notify, so the absence of its table is
+			// not a reason to reject the settings update.
+			try {
+				await bumpRunningExportWriteEpochs(trx);
+			} catch (error) {
+				if (isMissingTableError(error)) return;
+				throw error;
+			}
 		});
 	} finally {
 		invalidateSiteSettingsCache();

package/src/settings/types.ts

@@ -44,6 +44,8 @@ export interface SeoSettings {
 	defaultOgImage?: MediaReference;
 	/** Custom robots.txt content. If unset, a default is generated. */
 	robotsTxt?: string;
+	/** Add rules to robots.txt that ask AI crawlers not to use the site for training. */
+	disallowAiTraining?: boolean;
 	/** Google Search Console verification meta tag content */
 	googleVerification?: string;
 	/** Bing Webmaster Tools verification meta tag content */

package/src/settings/version.ts

@@ -0,0 +1,54 @@
+import type { Kysely, RawBuilder } from "kysely";
+import { sql } from "kysely";
+
+import { isPostgres } from "../database/dialect-helpers.js";
+import type { Database } from "../database/types.js";
+
+const SITE_OPTION_PREFIX = "site:%";
+
+/** Returns the canonical JSON representation of a site-settings revision fingerprint. */
+export function normalizeSiteSettingsVersion(input: string): string {
+	const decoded: unknown = JSON.parse(input);
+	if (!Array.isArray(decoded)) throw new Error("Invalid site settings version");
+	const entries: [string, string][] = [];
+	for (const entry of decoded) {
+		if (!Array.isArray(entry)) throw new Error("Invalid site settings version entry");
+		const name: unknown = entry[0];
+		const revision: unknown = entry[1];
+		if (typeof name !== "string" || typeof revision !== "string") {
+			throw new Error("Invalid site settings version entry");
+		}
+		entries.push([name, revision]);
+	}
+	return JSON.stringify(entries.toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+/**
+ * Builds the scalar query used to observe site-setting revisions alongside an
+ * existing read. It deliberately does not read option values.
+ */
+export function siteSettingsVersionQuery(db: Kysely<Database>): RawBuilder<string> {
+	if (isPostgres(db)) {
+		return sql<string>`(
+			select coalesce(
+				json_agg(json_build_array(name, revision) order by name)::text,
+				'[]'
+			)
+			from options
+			where name like ${SITE_OPTION_PREFIX}
+		)`;
+	}
+
+	return sql<string>`(
+		select coalesce(
+			json_group_array(json_array(name, revision)),
+			'[]'
+		)
+		from (
+			select name, revision
+			from options
+			where name glob ${"site:*"}
+			order by name
+		)
+	)`;
+}

package/src/taxonomies/index.ts

@@ -12,6 +12,7 @@
 
 import { sql, type Kysely } from "kysely";
 
+import { after } from "../after.js";
 import { taxonomyTag } from "../cache/chrome-tags.js";
 import {
 	parseTaxonomyCollections,
@@ -19,7 +20,13 @@ import {
 } from "../database/repositories/taxonomy-def.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
-import { getI18nConfig } from "../i18n/config.js";
+import { getI18nConfig, getLocaleChainRank, getLocaleCandidates } from "../i18n/config.js";
+import {
+	canonicalLocaleColumn,
+	localeMatches,
+	localeOrder,
+	storedLocaleOrder,
+} from "../i18n/query.js";
 import { resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
 import { getDb, resetTaxonomyNamesCache } from "../loader.js";
 import {
@@ -34,6 +41,12 @@ import { peekRequestCache, requestCached, setRequestCacheEntry } from "../reques
 import { getRequestContext } from "../request-context.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { isMissingTableError } from "../utils/db-errors.js";
+import {
+	createSingleFlightCache,
+	invalidateSingleFlightCache,
+	type SingleFlightCache,
+	singleFlightCached,
+} from "../utils/single-flight-cache.js";
 import { fetchVisibleTermCounts } from "./term-counts.js";
 import type { TaxonomyDef, TaxonomyTerm, TaxonomyTermRow } from "./types.js";
 
@@ -70,8 +83,12 @@ async function selectEntryTermRows(
 ): Promise<EntryTermRow[]> {
 	validateIdentifier(collection, "collection slug");
 	const tableName = `ec_${collection}`;
-	const preferredLocale = locale ? sql`${locale}` : sql`content.locale`;
 	const defaultLocale = getI18nConfig()?.defaultLocale ?? "en";
+	const preferredMatch = locale
+		? localeMatches("exact_term.locale", locale)
+		: sql`${canonicalLocaleColumn("exact_term.locale")} = ${canonicalLocaleColumn("content.locale")}`;
+	const defaultMatch = localeMatches("default_term.locale", defaultLocale);
+	const hasAliases = Object.keys(getI18nConfig()?.localeAliases ?? {}).length > 0;
 	const result = await sql<EntryTermRow>`
 		SELECT content.id AS entry_id,
 			coalesce(exact_term.id, default_term.id) AS id,
@@ -87,14 +104,35 @@ async function selectEntryTermRows(
 			AND pivot.collection = ${collection}
 		LEFT JOIN taxonomies AS exact_term
 			ON exact_term.translation_group = pivot.taxonomy_id
-			AND exact_term.locale = ${preferredLocale}
+			AND ${preferredMatch}
+			${
+				hasAliases
+					? sql`AND exact_term.id = (
+				SELECT candidate.id FROM taxonomies AS candidate
+				WHERE candidate.translation_group = pivot.taxonomy_id
+					AND ${locale ? localeMatches("candidate.locale", locale) : sql`${canonicalLocaleColumn("candidate.locale")} = ${canonicalLocaleColumn("content.locale")}`}
+				ORDER BY ${locale ? localeOrder("candidate.locale", locale) : storedLocaleOrder("candidate.locale")}, candidate.id LIMIT 1
+			)`
+					: sql``
+			}
 		LEFT JOIN taxonomies AS default_term
 			ON default_term.translation_group = pivot.taxonomy_id
-			AND default_term.locale = ${defaultLocale}
+			AND ${defaultMatch}
+			${
+				hasAliases
+					? sql`AND default_term.id = (
+				SELECT candidate.id FROM taxonomies AS candidate
+				WHERE candidate.translation_group = pivot.taxonomy_id
+					AND ${localeMatches("candidate.locale", defaultLocale)}
+				ORDER BY ${localeOrder("candidate.locale", defaultLocale)}, candidate.id LIMIT 1
+			)`
+					: sql``
+			}
 		WHERE content.id IN (${sql.join(entryIds.map((id) => sql`${id}`))})
 			AND coalesce(exact_term.id, default_term.id) IS NOT NULL
 			${taxonomyName ? sql`AND coalesce(exact_term.name, default_term.name) = ${taxonomyName}` : sql``}
-		ORDER BY coalesce(exact_term.label, default_term.label) ASC
+		ORDER BY coalesce(exact_term.label, default_term.label) ASC,
+			coalesce(exact_term.id, default_term.id) ASC
 	`.execute(db);
 	return result.rows;
 }
@@ -117,7 +155,9 @@ export function invalidateTermCache(): void {
  *
  * Stored on globalThis behind a Symbol key (same pattern as
  * `settings/index.ts`) so the bundler duplicating this module across SSR
- * chunks can't produce two independent caches.
+ * chunks can't produce two independent caches. It holds the resolved rows
+ * behind a reclaimable single-flight lock, never an in-flight promise (see
+ * `utils/single-flight-cache.ts`).
  *
  * When the distributed object cache is configured, it is authoritative and this
  * fallback is bypassed so cross-isolate epoch invalidation cannot be undercut
@@ -128,21 +168,15 @@ export function invalidateTermCache(): void {
  * skip both reading and writing the global holder and fall back to the
  * per-request cache (same precedent as `getTaxonomyNames` / byline field defs).
  */
-interface TaxonomyDefsHolder {
-	version: number;
-	/** The rows and the version they were fetched at. */
-	cache: Map<"all", { version: number; promise: Promise<TaxonomyDef[]> }>;
-}
-
-const TAXONOMY_DEFS_CACHE_KEY = Symbol.for("emdash:taxonomy-defs");
+const TAXONOMY_DEFS_CACHE_KEY = Symbol.for("emdash:taxonomy-defs@2");
 const taxonomyDefsStore = globalThis as Record<symbol, unknown>;
-const defsHolder: TaxonomyDefsHolder =
+const defsCache: SingleFlightCache<TaxonomyDef[]> =
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see settings/index.ts)
-	(taxonomyDefsStore[TAXONOMY_DEFS_CACHE_KEY] as TaxonomyDefsHolder | undefined) ??
+	(taxonomyDefsStore[TAXONOMY_DEFS_CACHE_KEY] as SingleFlightCache<TaxonomyDef[]> | undefined) ??
 	(() => {
-		const h: TaxonomyDefsHolder = { version: 0, cache: new Map() };
-		taxonomyDefsStore[TAXONOMY_DEFS_CACHE_KEY] = h;
-		return h;
+		const c = createSingleFlightCache<TaxonomyDef[]>();
+		taxonomyDefsStore[TAXONOMY_DEFS_CACHE_KEY] = c;
+		return c;
 	})();
 
 /**
@@ -152,8 +186,7 @@ const defsHolder: TaxonomyDefsHolder =
  * refresh on their next recycle — staleness bounded by isolate lifetime.
  */
 export function invalidateTaxonomyDefsCache(): void {
-	defsHolder.version++;
-	defsHolder.cache.clear();
+	invalidateSingleFlightCache(defsCache);
 	resetTaxonomyNamesCache();
 	invalidateTaxonomyObjectCache();
 }
@@ -165,8 +198,7 @@ export function invalidateTaxonomyDefsCache(): void {
  * `invalidateTaxonomyDefsCache()`.
  */
 export function resetTaxonomyDefsCacheForTests(): void {
-	defsHolder.version++;
-	defsHolder.cache.clear();
+	invalidateSingleFlightCache(defsCache);
 }
 
 /** Every locale's definition rows, straight from the database (no caching). */
@@ -181,28 +213,16 @@ async function fetchTaxonomyDefRows(): Promise<TaxonomyDef[]> {
 
 /**
  * Resolve the definition rows through the isolate fallback cache, bypassing it
- * for isolated databases. The returned promise is cached (not the resolved
- * value) so concurrent cold-isolate readers share one in-flight query; a
- * rejection evicts the entry so the next caller retries.
+ * for isolated databases.
  */
 function loadTaxonomyDefRows(): Promise<TaxonomyDef[]> {
 	if (getRequestContext()?.dbIsIsolated === true) {
 		return fetchTaxonomyDefRows();
 	}
-	const existing = defsHolder.cache.get("all");
-	if (existing && existing.version === defsHolder.version) {
-		return existing.promise;
-	}
-	const version = defsHolder.version;
-	const promise = fetchTaxonomyDefRows().catch((error: unknown) => {
-		const current = defsHolder.cache.get("all");
-		if (current && current.promise === promise) {
-			defsHolder.cache.delete("all");
-		}
-		throw error;
+	return singleFlightCached(defsCache, fetchTaxonomyDefRows, {
+		anchor: (promise) => after(() => promise),
+		ownerTimeoutMs: 30_000,
 	});
-	defsHolder.cache.set("all", { version, promise });
-	return promise;
 }
 
 /**
@@ -235,14 +255,14 @@ function resolveDefs(rows: readonly TaxonomyDef[], chain: readonly string[]): Ta
 	const byName = new Map<string, TaxonomyDef>();
 	for (const row of rows) {
 		const current = byName.get(row.name);
-		if (!current || rank(row.locale) < rank(current.locale)) byName.set(row.name, row);
+		if (
+			!current ||
+			getLocaleChainRank(row.locale, preference) < getLocaleChainRank(current.locale, preference)
+		) {
+			byName.set(row.name, row);
+		}
 	}
 	return [...byName.values()];
-
-	function rank(locale: string): number {
-		const index = preference.indexOf(locale);
-		return index === -1 ? preference.length : index;
-	}
 }
 
 /**
@@ -361,7 +381,11 @@ async function loadTaxonomyTerms(
 		.where("name", "=", def.name)
 		.orderBy("sort_order", "asc")
 		.orderBy("label", "asc");
-	if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
+	if (locale !== undefined) {
+		termsQuery = termsQuery
+			.where(localeMatches("locale", locale))
+			.orderBy(localeOrder("locale", locale), "asc");
+	}
 
 	const rows = await termsQuery.execute();
 
@@ -475,13 +499,28 @@ async function loadTerm(
 			.where("slug", "=", slug);
 
 	if (chain.length === 0) {
-		row = await selectTerm().orderBy("locale", "asc").executeTakeFirst();
+		row = await selectTerm().orderBy("locale", "asc").orderBy("id", "asc").executeTakeFirst();
 	} else {
-		row = undefined;
-		for (const locale of chain) {
-			row = await selectTerm().where("locale", "=", locale).executeTakeFirst();
-			if (row) break;
-		}
+		let offset = 0;
+		const candidates = chain.flatMap((locale) => {
+			const values = getLocaleCandidates(locale);
+			const result = values.map((candidate, index) => ({ candidate, rank: offset + index }));
+			offset += values.length;
+			return result;
+		});
+		const chainOrder = sql<number>`CASE ${sql.join(
+			candidates.map(
+				({ candidate, rank }) =>
+					sql`WHEN lower(locale) = ${candidate.toLowerCase()} THEN ${sql.lit(rank)}`,
+			),
+			sql` `,
+		)} ELSE ${sql.lit(offset)} END`;
+		row = await selectTerm()
+			.where((eb) => eb.or(chain.map((locale) => localeMatches("locale", locale))))
+			.orderBy(chainOrder, "asc")
+			.orderBy(localeOrder("locale", chain[0]), "asc")
+			.orderBy("id", "asc")
+			.executeTakeFirst();
 	}
 
 	if (!row) return null;
@@ -495,7 +534,11 @@ async function loadTerm(
 		.orderBy("sort_order", "asc")
 		.orderBy("label", "asc");
 	const termLocale = row.locale;
-	if (termLocale) childrenQuery = childrenQuery.where("locale", "=", termLocale);
+	if (termLocale) {
+		childrenQuery = childrenQuery
+			.where(localeMatches("locale", termLocale))
+			.orderBy(localeOrder("locale", termLocale), "asc");
+	}
 
 	const childRows = await childrenQuery.execute();
 

package/src/taxonomies/term-counts.ts

@@ -19,6 +19,7 @@ import { sql } from "kysely";
 import { buildStatusCondition, compoundSelectLimit } from "../database/dialect-helpers.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
+import { localeMatches } from "../i18n/query.js";
 import {
 	filterToRegisteredCollections,
 	noteStaleRegisteredCollections,
@@ -60,7 +61,7 @@ function collectionBranch(
 		WHERE e.translation_group = ct.entry_id
 			AND ct.collection = ${collection}
 			AND ct.taxonomy_id IN (SELECT translation_group FROM taxonomies WHERE name = ${taxonomyName})
-			${locale ? sql`AND e.locale = ${locale}` : sql``}
+			${locale ? sql`AND ${localeMatches("e.locale", locale)}` : sql``}
 			AND ${buildStatusCondition(db, "published", "e")}
 			AND e.deleted_at IS NULL
 		GROUP BY ct.taxonomy_id`;

package/src/utils/db-errors.ts

@@ -48,6 +48,21 @@ export function isMissingColumnError(error: unknown, column?: string): boolean {
 	return false;
 }
 
+const SQLITE_MISSING_COLUMN_RE =
+	/\bno such column:\s*([^:\r\n]+?)(?= - should this be a string literal in single-quotes\?|:|$)/;
+const POSTGRES_MISSING_COLUMN_RE = /\bcolumn\s+(.+?)\s+does not exist\b/;
+const COLUMN_IDENTIFIER_RE =
+	/^(?:"[a-z_][a-z0-9_]*"|[a-z_][a-z0-9_]*)(?:\.(?:"[a-z_][a-z0-9_]*"|[a-z_][a-z0-9_]*))?$/;
+
+/** The missing column, including its qualifier if present, normalized for comparison. */
+export function getMissingColumnIdentifier(error: unknown): string | undefined {
+	const message = messageOf(error);
+	const identifier =
+		SQLITE_MISSING_COLUMN_RE.exec(message)?.[1] ?? POSTGRES_MISSING_COLUMN_RE.exec(message)?.[1];
+	if (!identifier || !COLUMN_IDENTIFIER_RE.test(identifier.trim())) return undefined;
+	return identifier.trim().replaceAll('"', "");
+}
+
 /**
  * Returns true when `error` is a "table does not exist" error across the
  * dialects EmDash supports (D1/SQLite and PostgreSQL). Used by runtime

package/src/virtual-modules.d.ts

@@ -170,6 +170,7 @@ declare module "virtual:emdash/auth-providers" {
 		label: string;
 		LoginButton?: ComponentType;
 		LoginForm?: ComponentType;
+		loginHelp?: string | ComponentType;
 		SetupStep?: ComponentType<{ onComplete: () => void }>;
 	}