emdash 0.19.0 → 0.20.0

package/src/loader.ts

@@ -680,7 +680,12 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 
 				// Separate taxonomy / byline filters from field filters
 				let result: { rows: Record<string, unknown>[] };
-				let taxonomyFilter: { name: string; slugs: string[] } | null = null;
+				// Taxonomy filters AND together: each entry constrains the base
+				// row to match at least one of its slugs *within that taxonomy*.
+				// Term slugs are unique only within a taxonomy, so every filter
+				// keeps its own `name` and emits its own `EXISTS` clause rather
+				// than pooling slugs into one `IN`.
+				const taxonomyFilters: { name: string; slugs: string[] }[] = [];
 				// A byline filter matches entries credited to any of the given
 				// byline translation groups via the `_emdash_content_bylines`
 				// junction table. `null` means no byline filter; an empty
@@ -710,14 +715,8 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 								);
 								continue;
 							}
-							if (taxonomyFilter) {
-								console.warn(
-									`[emdash] where filter: only one taxonomy is supported per query, "${key}" ignored`,
-								);
-								continue;
-							}
 							const slugs = Array.isArray(value) ? value : [value];
-							taxonomyFilter = { name: key, slugs };
+							taxonomyFilters.push({ name: key, slugs });
 						} else {
 							fieldFilters[key] = value;
 						}
@@ -729,7 +728,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				// SQL on both dialects).
 				if (
 					(bylineFilter && bylineFilter.groups.length === 0) ||
-					(taxonomyFilter && taxonomyFilter.slugs.length === 0)
+					taxonomyFilters.some((f) => f.slugs.length === 0)
 				) {
 					return { entries: [], cacheHint: { tags: [type] } };
 				}
@@ -753,16 +752,26 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 					const fieldCondsSQL =
 						fieldConds.length > 0 ? sql`${sql.join(fieldConds, sql` AND `)}` : null;
 
-					const taxonomyCond = taxonomyFilter
-						? sql`AND EXISTS (
+					// One `EXISTS` per taxonomy, AND'd together: an entry must be
+					// tagged with a matching term in *every* requested taxonomy.
+					// Each clause pins its own `t.name`, so slugs never pool
+					// across taxonomies (they're only unique within one).
+					const taxonomyCond =
+						taxonomyFilters.length > 0
+							? sql`${sql.join(
+									taxonomyFilters.map(
+										(f) => sql`AND EXISTS (
 							SELECT 1 FROM content_taxonomies ct
 							INNER JOIN taxonomies t ON t.id = ct.taxonomy_id
 							WHERE ct.collection = ${type}
 								AND ct.entry_id = ${sql.ref(tableName)}.id
-								AND t.name = ${taxonomyFilter.name}
-								AND t.slug IN (${sql.join(taxonomyFilter.slugs.map((s) => sql`${s}`))})
-						)`
-						: sql``;
+								AND t.name = ${f.name}
+								AND t.slug IN (${sql.join(f.slugs.map((s) => sql`${s}`))})
+						)`,
+									),
+									sql` `,
+								)}`
+							: sql``;
 
 					// `_emdash_content_bylines.byline_id` stores the byline's
 					// translation_group (migration 040), so a credit spans every

package/src/plugins/manifest-schema.ts

@@ -8,8 +8,14 @@
  * - Marketplace ingest extends this with publishing-specific fields
  */
 
+import {
+	capabilitiesToDeclaredAccess,
+	declaredAccessToCapabilities,
+} from "@emdash-cms/plugin-types";
 import { z } from "zod";
 
+import type { PluginManifest } from "./types.js";
+
 // ── Enum values (must stay in sync with types.ts) ───────────────
 
 /**
@@ -219,16 +225,63 @@ const pluginAdminConfigSchema = z.object({
 		.optional(),
 });
 
+// ── declaredAccess ──────────────────────────────────────────────
+
+/**
+ * An operation's constraint object. Open vocabulary: keys the runtime
+ * recognises are enforced, others are advisory. The bundler emits `{}` for a
+ * granted operation; presence (not value) signals the grant.
+ */
+const accessConstraints = z.record(z.string(), z.unknown());
+
+/**
+ * Structured trust contract embedded in the bundle manifest. Mirrors
+ * `DeclaredAccess` in `@emdash-cms/plugin-types`. Categories are host
+ * subsystems; operations are modes of participation.
+ */
+const declaredAccessSchema = z.object({
+	content: z
+		.object({ read: accessConstraints.optional(), write: accessConstraints.optional() })
+		.optional(),
+	media: z
+		.object({ read: accessConstraints.optional(), write: accessConstraints.optional() })
+		.optional(),
+	network: z
+		.object({
+			// allowedHosts: absent = unrestricted; present = host-restricted. Reject
+			// an empty array (which the decoder would otherwise have to treat as
+			// deny-all) to match the record lexicon's `minLength: 1` and keep the
+			// "absent vs empty" distinction from ever reaching enforcement ambiguous.
+			request: z.object({ allowedHosts: z.array(z.string()).min(1).optional() }).optional(),
+		})
+		.optional(),
+	email: z
+		.object({
+			send: accessConstraints.optional(),
+			events: accessConstraints.optional(),
+			transport: accessConstraints.optional(),
+		})
+		.optional(),
+	page: z.object({ fragments: accessConstraints.optional() }).optional(),
+	users: z.object({ read: accessConstraints.optional() }).optional(),
+});
+
 // ── Main schema ─────────────────────────────────────────────────
 
 /**
  * Zod schema matching the PluginManifest interface from types.ts.
  *
  * Every JSON.parse of a manifest.json should validate through this.
+ *
+ * `declaredAccess` is the trust contract; `capabilities`/`allowedHosts` are the
+ * runtime's enforcement currency. Apply `reconcileManifestAccess` after parsing
+ * to make them consistent (declaredAccess authoritative when present). Kept a
+ * plain object (no `.transform`) because callers `.pick()`/`.extend()` it.
  */
 export const pluginManifestSchema = z.object({
 	id: z.string().min(1),
 	version: z.string().min(1),
+	declaredAccess: declaredAccessSchema.optional(),
 	capabilities: z.array(z.enum(PLUGIN_CAPABILITIES)),
 	allowedHosts: z.array(z.string()),
 	storage: z.record(z.string(), storageCollectionSchema),
@@ -254,6 +307,28 @@ export const pluginManifestSchema = z.object({
 
 export type ValidatedPluginManifest = z.infer<typeof pluginManifestSchema>;
 
+/**
+ * Reconcile a parsed manifest's trust contract with its enforcement currency.
+ * `declaredAccess` is authoritative: when present, `capabilities`/`allowedHosts`
+ * are re-derived from it so what the runtime enforces always matches what was
+ * recorded and consented to. A pre-migration bundle without `declaredAccess`
+ * has it derived from the legacy capability list instead. The result always
+ * carries both, mutually consistent. Apply this at every bundle-parse site.
+ */
+export function reconcileManifestAccess(manifest: ValidatedPluginManifest): PluginManifest {
+	const reconciled: ValidatedPluginManifest = manifest.declaredAccess
+		? { ...manifest, ...declaredAccessToCapabilities(manifest.declaredAccess) }
+		: {
+				...manifest,
+				declaredAccess: capabilitiesToDeclaredAccess(manifest.capabilities, manifest.allowedHosts),
+			};
+	// Block Kit admin elements are typed as `unknown` by the Zod schema (their
+	// Element shape is validated at render time), so the validated manifest
+	// needs a structural cast up to the runtime PluginManifest.
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- admin elements are unknown[] in Zod; Element type checked at render time
+	return reconciled as unknown as PluginManifest;
+}
+
 /**
  * Normalize a manifest hook entry — plain strings become `{ name }` objects.
  */

package/src/plugins/marketplace.ts

@@ -8,7 +8,7 @@
 
 import { createGzipDecoder, unpackTar } from "modern-tar";
 
-import { pluginManifestSchema } from "./manifest-schema.js";
+import { pluginManifestSchema, reconcileManifestAccess } from "./manifest-schema.js";
 import type { PluginManifest } from "./types.js";
 
 // ── Module-level regex patterns ───────────────────────────────────
@@ -495,10 +495,7 @@ export async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBun
 				"INVALID_BUNDLE",
 			);
 		}
-		// Elements are validated as unknown[] by Zod; cast to PluginManifest
-		// for the Element[] type (Block Kit validation happens at render time).
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Zod types elements as unknown[]; Element type validated at render time
-		manifest = result.data as unknown as PluginManifest;
+		manifest = reconcileManifestAccess(result.data);
 	} catch (err) {
 		if (err instanceof MarketplaceError) throw err;
 		throw new MarketplaceError(

package/src/plugins/types.ts

@@ -19,10 +19,13 @@ import type { Element } from "@emdash-cms/blocks";
 // (e.g. `import { PluginCapability } from "../plugins/types.js"`).
 import {
 	CAPABILITY_RENAMES,
+	capabilitiesToDeclaredAccess,
+	declaredAccessToCapabilities,
 	isDeprecatedCapability,
 	normalizeCapabilities,
 	normalizeCapability,
 	type CurrentPluginCapability,
+	type DeclaredAccess,
 	type DeprecatedPluginCapability,
 	type ManifestHookEntry,
 	type ManifestRouteEntry,
@@ -40,10 +43,13 @@ import type { FieldType } from "../schema/types.js";
 
 export {
 	CAPABILITY_RENAMES,
+	capabilitiesToDeclaredAccess,
+	declaredAccessToCapabilities,
 	isDeprecatedCapability,
 	normalizeCapabilities,
 	normalizeCapability,
 	type CurrentPluginCapability,
+	type DeclaredAccess,
 	type DeprecatedPluginCapability,
 	type ManifestHookEntry,
 	type ManifestRouteEntry,
@@ -1336,6 +1342,12 @@ export interface PluginAdminExports {
 export interface PluginManifest {
 	id: string;
 	version: string;
+	/**
+	 * The trust contract (see `@emdash-cms/plugin-types`). Authoritative;
+	 * `capabilities`/`allowedHosts` are derived from it at the parse boundary
+	 * via `reconcileManifestAccess`. Optional during the wire-format migration.
+	 */
+	declaredAccess?: DeclaredAccess;
 	capabilities: PluginCapability[];
 	allowedHosts: string[];
 	storage: PluginStorageConfig;

package/src/query.ts

@@ -247,6 +247,17 @@ function dataStr(data: Record<string, unknown>, key: string, fallback = ""): str
 	return typeof val === "string" ? val : fallback;
 }
 
+/** Safely read a date-like field from a Record */
+function dataDate(data: Record<string, unknown>, key: string): Date | undefined {
+	const val = data[key];
+	if (val instanceof Date) {
+		return Number.isNaN(val.getTime()) ? undefined : val;
+	}
+	if (typeof val !== "string" && typeof val !== "number") return undefined;
+	const date = new Date(val);
+	return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
 /** Type guard for Record<string, unknown> */
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -602,10 +613,10 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 	function isVisible(entry: ContentEntry<D>): boolean {
 		const data = entryData(entry);
 		const status = dataStr(data, "status");
-		const scheduledAt = dataStr(data, "scheduledAt") || undefined;
+		const scheduledAt = dataDate(data, "scheduledAt");
 		const isPublished = status === "published";
 		const isScheduledAndReady =
-			status === "scheduled" && scheduledAt && new Date(scheduledAt) <= new Date();
+			status === "scheduled" && scheduledAt !== undefined && scheduledAt.getTime() <= Date.now();
 		return isPublished || !!isScheduledAndReady;
 	}
 

package/src/request-context.ts

@@ -39,6 +39,13 @@ export interface RequestMetrics {
 	dbLastOffset: number | null;
 	cacheHits: number;
 	cacheMisses: number;
+	/**
+	 * Physical database round trips. Differs from `dbCount` (logical queries)
+	 * when a backend batches: the DO SQL driver coalesces same-turn SELECTs into
+	 * one RPC, so `rpcCount` can be far lower than `dbCount`. Bumped by the
+	 * adapter, not the Kysely log hook.
+	 */
+	rpcCount: number;
 }
 
 export function createRequestMetrics(start: number): RequestMetrics {
@@ -50,6 +57,7 @@ export function createRequestMetrics(start: number): RequestMetrics {
 		dbLastOffset: null,
 		cacheHits: 0,
 		cacheMisses: 0,
+		rpcCount: 0,
 	};
 }
 

package/src/schema/types.ts

@@ -102,7 +102,16 @@ export type CollectionSource =
 /** Sub-field definition for repeater fields */
 export interface RepeaterSubField {
 	slug: string;
-	type: "string" | "text" | "url" | "number" | "integer" | "boolean" | "datetime" | "select";
+	type:
+		| "string"
+		| "text"
+		| "url"
+		| "number"
+		| "integer"
+		| "boolean"
+		| "datetime"
+		| "select"
+		| "image";
 	label: string;
 	required?: boolean;
 	options?: string[]; // For select sub-fields
@@ -118,6 +127,7 @@ export const REPEATER_SUB_FIELD_TYPES = [
 	"boolean",
 	"datetime",
 	"select",
+	"image",
 ] as const;
 
 export interface FieldValidation {

package/src/seo/index.ts

@@ -30,6 +30,7 @@
  */
 
 import type { ContentSeo } from "../database/repositories/types.js";
+import { buildSeoImageUrl } from "./media-url.js";
 
 const TRAILING_SLASH_RE = /\/$/;
 const ABSOLUTE_URL_RE = /^https?:\/\//i;
@@ -117,7 +118,7 @@ export function getSeoMeta<T>(content: SeoContentInput<T>, options: SeoMetaOptio
 		null;
 
 	// OG image: SEO image > default
-	const ogImage = seo.image ? buildMediaUrl(seo.image, siteUrl) : (defaultOgImage ?? null);
+	const ogImage = seo.image ? buildSeoImageUrl(seo.image, siteUrl) : (defaultOgImage ?? null);
 
 	// Canonical: explicit > path-based > null
 	let canonical: string | null = null;
@@ -159,30 +160,3 @@ export function getSeoMeta<T>(content: SeoContentInput<T>, options: SeoMetaOptio
 export function getContentSeo<T>(content: SeoContentInput<T>): ContentSeo | undefined {
 	return content.seo ?? content.data.seo;
 }
-
-/**
- * Build a media URL from a media reference ID.
- * If it's already an absolute URL, return as-is.
- */
-function buildMediaUrl(imageRef: string, siteUrl?: string): string {
-	// If already an absolute URL, return as-is
-	if (ABSOLUTE_URL_RE.test(imageRef)) {
-		return imageRef;
-	}
-
-	// Root-relative path — the CMS SEO panel stores seo_image as
-	// "/_emdash/api/media/file/01KS....svg" (already includes the API
-	// prefix). Without this branch we'd re-prefix and produce
-	// "${siteUrl}/_emdash/api/media/file//_emdash/api/media/file/<id>"
-	// which 404s and breaks <meta property="og:image">.
-	if (imageRef.startsWith("/")) {
-		return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${imageRef}` : imageRef;
-	}
-
-	// Bare media_id — build the full media API path
-	const mediaPath = `/_emdash/api/media/file/${imageRef}`;
-	if (siteUrl) {
-		return `${siteUrl.replace(TRAILING_SLASH_RE, "")}${mediaPath}`;
-	}
-	return mediaPath;
-}

package/src/seo/media-url.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolve a stored SEO image reference to a URL.
+ *
+ * The CMS SEO panel stores `seo_image` in one of these shapes:
+ * - an absolute URL (`https://...`) — returned as-is;
+ * - a root-relative path that already includes the media API prefix
+ *   (`/_emdash/api/media/file/01KS....webp`) — prefixed with `siteUrl`;
+ * - a bare media id (`01KS...`) — expanded to the media API path, then
+ *   prefixed with `siteUrl`.
+ *
+ * Shared by the SEO meta builder (`og:image`) and the sitemap route
+ * (`<image:image>`) so both resolve image references identically.
+ */
+const TRAILING_SLASH_RE = /\/$/;
+const ABSOLUTE_URL_RE = /^https?:\/\//i;
+
+export function buildSeoImageUrl(imageRef: string, siteUrl?: string): string {
+	// Already absolute — use as-is.
+	if (ABSOLUTE_URL_RE.test(imageRef)) {
+		return imageRef;
+	}
+
+	// Root-relative path (already includes the media API prefix). Without
+	// this branch we'd re-prefix and produce a doubled path that 404s.
+	if (imageRef.startsWith("/")) {
+		return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${imageRef}` : imageRef;
+	}
+
+	// Bare media id — build the full media API path.
+	const mediaPath = `/_emdash/api/media/file/${imageRef}`;
+	return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${mediaPath}` : mediaPath;
+}

package/src/settings/index.ts

@@ -7,12 +7,19 @@
 
 import type { Kysely } from "kysely";
 
+import { after } from "../after.js";
 import { MediaRepository } from "../database/repositories/media.js";
 import { OptionsRepository } from "../database/repositories/options.js";
 import type { Database } from "../database/types.js";
 import { getDb } from "../loader.js";
 import { peekRequestCache, requestCached } from "../request-cache.js";
 import type { Storage } from "../storage/types.js";
+import {
+	createIsolateCache,
+	type IsolateCache,
+	invalidateIsolateCache,
+	isolateCachedAsync,
+} from "../utils/isolate-cache.js";
 import type { SiteSettings, SiteSettingKey, MediaReference, SeoSettings } from "./types.js";
 
 /** Prefix for site settings in the options table */
@@ -27,29 +34,22 @@ const SETTINGS_PREFIX = "site:";
  * once-per-isolate. Cross-isolate staleness is bounded by isolate lifetime
  * (workerd typically recycles within minutes); acceptable for chrome.
  *
- * Stored on globalThis with a Symbol.for key so Vite SSR chunk duplication
- * doesn't produce two independent caches (same pattern as request-context.ts).
- *
- * Invalidation: every `site:*` write bumps `version`. Reads compare the
- * cached promise's version against the current version and refetch on
- * mismatch. Caching the promise (not the resolved value) lets concurrent
- * cold-isolate readers share the in-flight query.
+ * Backed by isolate-cache.ts: concurrent cold-isolate reads coalesce onto one
+ * query via a reclaimable single-flight lock and the resolved *value* is
+ * cached — never a shared in-flight promise, so a cancelled request can't
+ * poison the isolate (see that file's header). Stored on globalThis with a
+ * Symbol.for key so Vite SSR chunk duplication doesn't produce two
+ * independent caches (same pattern as request-context.ts).
  */
-interface SiteSettingsHolder {
-	version: number;
-	cached: Promise<Partial<SiteSettings>> | null;
-	cachedVersion: number;
-}
-
 const SITE_SETTINGS_CACHE_KEY = Symbol.for("emdash:site-settings");
 const g = globalThis as Record<symbol, unknown>;
-const holder: SiteSettingsHolder =
+const settingsCache: IsolateCache<Partial<SiteSettings>> =
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
-	(g[SITE_SETTINGS_CACHE_KEY] as SiteSettingsHolder | undefined) ??
+	(g[SITE_SETTINGS_CACHE_KEY] as IsolateCache<Partial<SiteSettings>> | undefined) ??
 	(() => {
-		const h: SiteSettingsHolder = { version: 0, cached: null, cachedVersion: -1 };
-		g[SITE_SETTINGS_CACHE_KEY] = h;
-		return h;
+		const c = createIsolateCache<Partial<SiteSettings>>();
+		g[SITE_SETTINGS_CACHE_KEY] = c;
+		return c;
 	})();
 
 /**
@@ -60,9 +60,7 @@ const holder: SiteSettingsHolder =
  * own cached copy until they expire — staleness bounded by isolate lifetime.
  */
 export function invalidateSiteSettingsCache(): void {
-	holder.version++;
-	holder.cached = null;
-	holder.cachedVersion = -1;
+	invalidateIsolateCache(settingsCache);
 }
 
 /**
@@ -210,25 +208,19 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
  * ```
  */
 export function getSiteSettings(): Promise<Partial<SiteSettings>> {
-	return requestCached("siteSettings", () => {
-		const versionAtCall = holder.version;
-		if (holder.cached && holder.cachedVersion === versionAtCall) {
-			return holder.cached;
-		}
-		const fetchPromise = (async () => {
-			const db = await getDb();
-			return getSiteSettingsWithDb(db);
-		})().catch((error) => {
-			if (holder.cached === fetchPromise) {
-				holder.cached = null;
-				holder.cachedVersion = -1;
-			}
-			throw error;
-		});
-		holder.cached = fetchPromise;
-		holder.cachedVersion = versionAtCall;
-		return fetchPromise;
-	});
+	// requestCached dedupes within a single request; isolateCachedAsync
+	// coalesces across requests and caches the resolved value for the
+	// isolate's lifetime without ever sharing an awaitable promise.
+	return requestCached("siteSettings", () =>
+		isolateCachedAsync(
+			settingsCache,
+			async () => {
+				const db = await getDb();
+				return getSiteSettingsWithDb(db);
+			},
+			{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
+		),
+	);
 }
 
 /**

package/src/taxonomies/index.ts

@@ -120,15 +120,10 @@ export async function getTaxonomyTerms(
 		if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
 		const rows = await termsQuery.execute();
 
-		// Counts are keyed by translation_group (what the pivot stores).
-		const countsResult = await db
-			.selectFrom("content_taxonomies")
-			.select(["taxonomy_id"])
-			.select((eb) => eb.fn.count<number>("entry_id").as("count"))
-			.groupBy("taxonomy_id")
-			.execute();
-		const counts = new Map<string, number>();
-		for (const row of countsResult) counts.set(row.taxonomy_id, row.count);
+		// Counts are keyed by translation_group (what the pivot stores) and are
+		// locale-independent, so the aggregate is shared across every taxonomy
+		// rendered in this request (Categories + Tags widgets, etc.).
+		const counts = await getTaxonomyTermCounts();
 
 		const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
 			id: row.id,
@@ -157,6 +152,27 @@ export async function getTaxonomyTerms(
 	});
 }
 
+/**
+ * Per-translation-group usage counts across all taxonomies, in one aggregate
+ * scan of `content_taxonomies`. Counts are locale-independent (the pivot stores
+ * translation_group), so a single request-cached entry serves every taxonomy
+ * that renders during the request.
+ */
+function getTaxonomyTermCounts(): Promise<Map<string, number>> {
+	return requestCached("taxonomy-term-counts", async () => {
+		const db = await getDb();
+		const countsResult = await db
+			.selectFrom("content_taxonomies")
+			.select(["taxonomy_id"])
+			.select((eb) => eb.fn.count<number>("entry_id").as("count"))
+			.groupBy("taxonomy_id")
+			.execute();
+		const counts = new Map<string, number>();
+		for (const row of countsResult) counts.set(row.taxonomy_id, row.count);
+		return counts;
+	});
+}
+
 /**
  * Get a single term by (taxonomy, slug). Honours the fallback chain — if the
  * slug exists in a fallback locale, we return that row (useful for deep-linking
@@ -290,10 +306,57 @@ export async function getTermsForEntries(
 	for (const id of uniqueIds) result.set(id, []);
 	if (uniqueIds.length === 0) return result;
 
-	const db = await getDb();
 	const locale = resolveLocale(options.locale);
+	const localeKey = locale ?? "*";
 
-	for (const chunk of chunks(uniqueIds, SQL_BATCH_SIZE)) {
+	// Entry-term hydration (getAllTermsForEntries -> primeEntryTermsCache)
+	// seeds the per-entry cache under the same key getEntryTerms uses:
+	// `terms:${collection}:${entryId}:${taxonomyName}:${localeKey}`, storing a
+	// TaxonomyTerm[] (including `[]` for entries with no terms). Satisfy those
+	// from cache and run the batched query only for the ids that missed.
+	const missedIds: string[] = [];
+	type CacheRead = { id: string; terms: TaxonomyTerm[] } | { id: string; miss: true };
+	const cacheReads: Array<Promise<CacheRead>> = [];
+	for (const id of uniqueIds) {
+		const cached = peekRequestCache<TaxonomyTerm[]>(
+			`terms:${collection}:${id}:${taxonomyName}:${localeKey}`,
+		);
+		if (cached) {
+			// A peeked promise can reject (e.g. a sibling getEntryTerms hit a
+			// missing table). Treat a rejection as a cache miss so the batched
+			// query path -- and its isMissingTableError guard below -- still runs,
+			// rather than propagating an uncaught error.
+			cacheReads.push(
+				cached.then(
+					(terms): CacheRead => ({ id, terms }),
+					(): CacheRead => ({ id, miss: true }),
+				),
+			);
+		} else {
+			missedIds.push(id);
+		}
+	}
+	for (const read of await Promise.all(cacheReads)) {
+		if ("miss" in read) {
+			missedIds.push(read.id);
+			continue;
+		}
+		// Return a private copy. The cached array and its term objects are shared
+		// with getEntryTerms/getAllTermsForEntries (primeEntryTermsCache stores
+		// the same references), so a caller that mutates the result -- sorting in
+		// place, pushing into `children` -- must not poison the cache. The
+		// pre-cache implementation always returned freshly built arrays.
+		result.set(
+			read.id,
+			read.terms.map((t) => ({ ...t, children: [...t.children] })),
+		);
+	}
+
+	if (missedIds.length === 0) return result;
+
+	const db = await getDb();
+
+	for (const chunk of chunks(missedIds, SQL_BATCH_SIZE)) {
 		let rows;
 		try {
 			let query = db
@@ -311,7 +374,10 @@ export async function getTermsForEntries(
 				])
 				.where("content_taxonomies.collection", "=", collection)
 				.where("content_taxonomies.entry_id", "in", chunk)
-				.where("taxonomies.name", "=", taxonomyName);
+				.where("taxonomies.name", "=", taxonomyName)
+				// Match the order getAllTermsForEntries (the cache primer) uses, so
+				// cache-hit and DB-miss entries in one result are ordered consistently.
+				.orderBy("taxonomies.label", "asc");
 			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
 			rows = await query.execute();
 		} catch (error) {