emdash 0.22.0 → 0.24.0

package/src/emdash-runtime.ts

@@ -244,6 +244,15 @@ export interface MediaProviderEntry {
  */
 export interface MediaProviderContext {
 	db: Kysely<Database>;
+	/**
+	 * Resolver for the live connection, preferred over `db` by providers that
+	 * query EmDash's database. Resolves the current request/event-scoped
+	 * connection from ALS so connection-backed adapters (Postgres over
+	 * Hyperdrive) don't reuse the per-isolate singleton's socket across events.
+	 * Providers should resolve per operation rather than capturing `db` once.
+	 * Omitted-safe: falls back to `db` for stateless adapters (D1, Node SQLite).
+	 */
+	getDb?: () => Kysely<Database>;
 	storage: Storage | null;
 }
 
@@ -262,6 +271,16 @@ export interface RuntimeDependencies {
 	plugins: ResolvedPlugin[];
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	createDialect: (config: any) => Dialect;
+	/**
+	 * Factory for a dialect that batches same-turn reads into one round trip
+	 * ({@link EmDashRuntime.create} uses it for the cold-start read phase).
+	 * Present only on batching backends (D1, DO); absent backends fall back to
+	 * the singleton. Returns a fresh connection each call — it must never be the
+	 * long-lived singleton, whose coalescing buffer would be shared across
+	 * requests.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	createCoalescingDialect?: (config: any) => Dialect | null;
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	createStorage: ((config: any) => Storage) | null;
 	sandboxEnabled: boolean;
@@ -323,6 +342,7 @@ export interface EmDashRuntimeParts {
 	allPipelinePlugins: ResolvedPlugin[];
 	pipelineFactoryOptions: {
 		db: Kysely<Database>;
+		getDb?: () => Kysely<Database>;
 		storage?: Storage;
 		siteInfo?: { siteName?: string; siteUrl?: string; locale?: string };
 	};
@@ -370,6 +390,28 @@ function getDbHolder(): DbHolder {
 	}
 	return holder;
 }
+
+/**
+ * Auto-seed runs at most once per isolate per database. Its lock + "done" set
+ * live on globalThis (same bundler-duplication reasoning as the db cache) so a
+ * reclaimed-and-rerun `create()` can't seed a second time concurrently. The
+ * lock polls rather than sharing a promise, so it is safe to await across a
+ * cancelled owner in workerd.
+ */
+const SEED_HOLDER_KEY = Symbol.for("emdash:seed-state");
+interface SeedHolder {
+	done: Set<string>;
+	lock: InitLock;
+}
+function getSeedHolder(): SeedHolder {
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis symbol slot, written only below
+	let holder = globalSymbolStore[SEED_HOLDER_KEY] as SeedHolder | undefined;
+	if (!holder) {
+		holder = { done: new Set<string>(), lock: createInitLock() };
+		globalSymbolStore[SEED_HOLDER_KEY] = holder;
+	}
+	return holder;
+}
 const storageCache = new Map<string, Storage>();
 const sandboxedPluginCache = new Map<string, SandboxedPluginInstance>();
 /**
@@ -414,7 +456,20 @@ export class EmDashRuntime {
 	readonly configuredPlugins: ResolvedPlugin[];
 	readonly sandboxedPlugins: Map<string, SandboxedPluginInstance>;
 	readonly sandboxedPluginEntries: SandboxedPluginEntry[];
-	readonly schemaRegistry: SchemaRegistry;
+	/**
+	 * Schema registry bound to the current request/event-scoped connection.
+	 * Built per access (SchemaRegistry just wraps a db) against `this.db`, the
+	 * ALS-aware getter — never a captured snapshot of the singleton. On a
+	 * connection-backed adapter (Postgres over Hyperdrive) a captured singleton
+	 * would query a socket opened by an earlier event and trip workerd's
+	 * cross-request I/O guard; the catch in handlers like handleContentUpdate
+	 * would then silently treat a revision-enabled collection as non-revisioned
+	 * and write draft edits to live columns. Same reasoning as the per-call
+	 * registry in _buildManifest().
+	 */
+	get schemaRegistry(): SchemaRegistry {
+		return new SchemaRegistry(this.db);
+	}
 	private _hooks!: HookPipeline;
 	readonly config: EmDashConfig;
 	readonly mediaProviders: Map<string, MediaProvider>;
@@ -445,6 +500,7 @@ export class EmDashRuntime {
 	/** Factory options for the hook pipeline context factory */
 	private pipelineFactoryOptions: {
 		db: Kysely<Database>;
+		getDb?: () => Kysely<Database>;
 		storage?: Storage;
 		siteInfo?: { siteName?: string; siteUrl?: string; locale?: string };
 	};
@@ -475,7 +531,6 @@ export class EmDashRuntime {
 		this.configuredPlugins = parts.configuredPlugins;
 		this.sandboxedPlugins = parts.sandboxedPlugins;
 		this.sandboxedPluginEntries = parts.sandboxedPluginEntries;
-		this.schemaRegistry = new SchemaRegistry(parts.db);
 		this._hooks = parts.hooks;
 		this.enabledPlugins = parts.enabledPlugins;
 		this.pluginStates = parts.pluginStates;
@@ -621,7 +676,9 @@ export class EmDashRuntime {
 		// The old pipeline's contextFactoryOptions were built up incrementally
 		// via setContextFactory calls during create(). We replay them here.
 		if (this.email) {
-			newPipeline.setContextFactory({ db: this.db, emailPipeline: this.email });
+			// db/getDb are already wired by createHookPipeline above (they live in
+			// pipelineFactoryOptions), so the merge only adds emailPipeline.
+			newPipeline.setContextFactory({ emailPipeline: this.email });
 		}
 		if (this.cronScheduler) {
 			const scheduler = this.cronScheduler;
@@ -985,6 +1042,22 @@ export class EmDashRuntime {
 		// Initialize database (connects, runs migrations if needed)
 		const db = await phase("rt.db", "DB init + migrations", () => EmDashRuntime.getDatabase(deps));
 
+		// Resolver for the live connection, mirroring the `get db()` getter
+		// below (which can't be used here — the runtime instance doesn't exist
+		// yet). Long-lived subsystems built during create() (cron executor,
+		// plugin context factory, media providers) capture this resolver rather
+		// than the `db` snapshot, so a connection-backed adapter (Postgres over
+		// Hyperdrive) serves their queries from the current request/event-scoped
+		// connection in ALS instead of the per-isolate singleton — whose socket
+		// belongs to an earlier request and would trip workerd's cross-request
+		// I/O guard. Stateless adapters (D1, Node SQLite) set no ALS db on most
+		// paths, so this falls back to the singleton: unchanged behavior.
+		const resolveDb = (): Kysely<Database> => {
+			const ctx = getRequestContext();
+			// eslint-disable-next-line typescript/no-unsafe-type-assertion -- ALS db is typed unknown to avoid a circular import; middleware always sets a Kysely<Database>
+			return (ctx?.db as Kysely<Database> | undefined) ?? db;
+		};
+
 		// Validate EMDASH_ENCRYPTION_KEY once here so a malformed value
 		// surfaces in startup logs instead of as request-time 500s. The key
 		// itself is not yet consumed (a follow-up PR adds plugin-secret
@@ -998,47 +1071,156 @@ export class EmDashRuntime {
 		// Initialize storage (sync)
 		const storage = EmDashRuntime.getStorage(deps);
 
-		// Fetch plugin states and site info concurrently — independent reads
-		// against different tables (_plugin_state vs options), so they share
-		// one round-trip window instead of paying two sequential ones. Each
-		// phase() wrapper still records that phase's own duration, and each
-		// body keeps its own non-fatal catch.
 		let pluginStates: Map<string, string> = new Map();
 		let siteInfo: { siteName?: string; siteUrl?: string; locale?: string } | undefined;
-		await Promise.all([
-			// Fetch plugin states from database
+		// "Already set up" by default so a read failure (e.g. tables absent on a
+		// pre-migration db) skips seeding rather than seeding a half-built db.
+		let seedGate = { collectionCount: 1, setupDone: true };
+
+		// Seeding must only touch the configured singleton, never a borrowed
+		// per-request db (playground / DO preview) or the loader-fallback db.
+		const reqCtx = getRequestContext();
+		const ownsConfiguredDb = !!deps.config.database && !(reqCtx?.dbIsIsolated && reqCtx.db);
+
+		// Run the init reads on a coalescing connection so the concurrent
+		// same-turn reads flush as one batch() round trip. The singleton can't:
+		// its plain SqliteAdapter reports supportsMultipleConnections=false, so
+		// Kysely's connection mutex serializes concurrent reads into N round
+		// trips. The connection is per-init and discarded — the long-lived
+		// singleton must never coalesce or one request's reads could land in
+		// another's batch. Backends without a coalescing dialect (Node/SQLite)
+		// fall back to the singleton, where serialization costs nothing.
+		let readDb = db;
+		let readDbDisposable: Kysely<Database> | undefined;
+		if (ownsConfiguredDb && deps.createCoalescingDialect && deps.config.database) {
+			try {
+				const dialect = deps.createCoalescingDialect(deps.config.database.config);
+				if (dialect) {
+					readDb = new Kysely<Database>({ dialect, log: kyselyLogOption() });
+					readDbDisposable = readDb;
+				}
+			} catch {
+				readDb = db;
+			}
+		}
+		const optionsRepo = new OptionsRepository(readDb);
+
+		const readSiteInfo = async () => {
+			const siteOpts = await optionsRepo.getMany<string>([
+				"emdash:site_title",
+				"emdash:site_url",
+				"emdash:locale",
+			]);
+			return {
+				siteName: siteOpts.get("emdash:site_title") ?? undefined,
+				siteUrl: siteOpts.get("emdash:site_url") ?? undefined,
+				locale: siteOpts.get("emdash:locale") ?? undefined,
+			};
+		};
+
+		const coldStartReads: Array<Promise<void>> = [
 			phase("rt.plugins", "Plugin states", async () => {
 				try {
-					const states = await db
+					const states = await readDb
 						.selectFrom("_plugin_state")
 						.select(["plugin_id", "status"])
 						.execute();
 					pluginStates = new Map(states.map((s) => [s.plugin_id, s.status]));
 				} catch {
-					// Plugin state table may not exist yet
+					// _plugin_state may not exist yet on a pre-migration db.
 				}
 			}),
-			// Load site info for plugin context extensions (1 batch query instead of 3)
 			phase("rt.site", "Site info options", async () => {
 				try {
-					const optionsRepo = new OptionsRepository(db);
-					const siteOpts = await optionsRepo.getMany<string>([
-						"emdash:site_title",
-						"emdash:site_url",
-						"emdash:locale",
-					]);
-					siteInfo = {
-						siteName: siteOpts.get("emdash:site_title") ?? undefined,
-						siteUrl: siteOpts.get("emdash:site_url") ?? undefined,
-						locale: siteOpts.get("emdash:locale") ?? undefined,
-					};
+					siteInfo = await readSiteInfo();
 				} catch {
-					// Options table may not exist yet (pre-setup)
+					// options may not exist yet on a pre-migration db.
 				}
 			}),
-		]);
+		];
+
+		if (ownsConfiguredDb) {
+			coldStartReads.push(
+				phase("rt.seedcheck", "Auto-seed gate", async () => {
+					try {
+						const [collectionCount, setupOption] = await Promise.all([
+							readDb
+								.selectFrom("_emdash_collections")
+								.select((eb) => eb.fn.countAll<number>().as("count"))
+								.executeTakeFirstOrThrow(),
+							readDb
+								.selectFrom("options")
+								.select("value")
+								.where("name", "=", "emdash:setup_complete")
+								.executeTakeFirst(),
+						]);
+						const setupDone = (() => {
+							try {
+								return !!setupOption && JSON.parse(setupOption.value) === true;
+							} catch {
+								return false;
+							}
+						})();
+						seedGate = { collectionCount: collectionCount.count, setupDone };
+					} catch {
+						// Leave the "already set up" default so a read failure never
+						// triggers a seed onto a half-built db.
+					}
+				}),
+			);
+		}
+
+		await Promise.all(coldStartReads);
+
+		// Auto-seed the default schema for a first load that skipped the setup
+		// wizard (the wizard and dev-bypass apply seeds explicitly). Run under a
+		// per-isolate lock keyed by the configured db so a reclaimed-and-rerun
+		// create() can't apply the seed a second time concurrently.
+		if (seedGate.collectionCount === 0 && !seedGate.setupDone) {
+			const seedKey = deps.config.database?.entrypoint ?? "default";
+			const seedHolder = getSeedHolder();
+			try {
+				await initWithLock(
+					seedHolder.lock,
+					() => (seedHolder.done.has(seedKey) ? true : undefined),
+					async () => {
+						const { applySeed } = await import("./seed/apply.js");
+						const { loadSeed } = await import("./seed/load.js");
+						const { validateSeed } = await import("./seed/validate.js");
+
+						const seed = await loadSeed();
+						const validation = validateSeed(seed);
+						if (validation.valid) {
+							await applySeed(db, seed, { onConflict: "skip" });
+							console.log("Auto-seeded default collections");
+						}
+						seedHolder.done.add(seedKey);
+						return true;
+					},
+					{ deadlineMs: DB_INIT_DEADLINE_MS, anchor: (promise) => after(() => promise) },
+				);
+				// The site-info read ran before the seed wrote its defaults, so
+				// refresh the snapshot the plugin context sees.
+				try {
+					siteInfo = await readSiteInfo();
+				} catch {
+					// Non-fatal — plugin context falls back to undefined fields.
+				}
+			} catch {
+				// Non-fatal — a failed seed (e.g. missing seed module) leaves the
+				// site un-seeded; a later request retries.
+			}
+		}
+
+		// The read connection is single-use; everything below uses the singleton.
+		if (readDbDisposable) {
+			try {
+				await readDbDisposable.destroy();
+			} catch {
+				// Non-fatal — the underlying binding is shared and needs no teardown.
+			}
+		}
 
-		// Build set of enabled plugins
 		const enabledPlugins = new Set<string>();
 		for (const plugin of deps.plugins) {
 			const status = pluginStates.get(plugin.id);
@@ -1154,9 +1336,15 @@ export class EmDashRuntime {
 		// Filter to currently enabled plugins for the initial pipeline
 		const enabledPluginList = allPipelinePlugins.filter((p) => enabledPlugins.has(p.id));
 
-		// Create hook pipeline
+		// Create hook pipeline. getDb travels here (not just via the email
+		// setContextFactory call below) so it survives rebuildHookPipeline(),
+		// which reconstructs the factory from pipelineFactoryOptions. Without it,
+		// toggling a plugin on an email-less deployment would silently revert
+		// plugin contexts to the singleton db — re-breaking connection-backed
+		// adapters. See #1622.
 		const pipelineFactoryOptions = {
 			db,
+			getDb: resolveDb,
 			storage: storage ?? undefined,
 			siteInfo,
 		};
@@ -1208,7 +1396,7 @@ export class EmDashRuntime {
 		// Initialize media providers
 		const mediaProviders = new Map<string, MediaProvider>();
 		const mediaProviderEntries = deps.mediaProviderEntries ?? [];
-		const providerContext: MediaProviderContext = { db, storage };
+		const providerContext: MediaProviderContext = { db, storage, getDb: resolveDb };
 
 		for (const entry of mediaProviderEntries) {
 			try {
@@ -1249,8 +1437,10 @@ export class EmDashRuntime {
 		};
 
 		// Wire email pipeline into context factory (independent of cron —
-		// must not be inside the cron try/catch or ctx.email breaks when cron fails)
-		pipeline.setContextFactory({ db, emailPipeline });
+		// must not be inside the cron try/catch or ctx.email breaks when cron fails).
+		// db/getDb were already set via pipelineFactoryOptions above; merge only
+		// adds emailPipeline.
+		pipeline.setContextFactory({ emailPipeline });
 
 		let cronExecutor: CronExecutor | null = null;
 		let cronScheduler: CronScheduler | null = null;
@@ -1262,7 +1452,7 @@ export class EmDashRuntime {
 
 		await phase("rt.cron", "Cron init (recovery deferred post-response)", async () => {
 			try {
-				cronExecutor = new CronExecutor(db, invokeCronHook);
+				cronExecutor = new CronExecutor(resolveDb, invokeCronHook);
 
 				// Recover stale locks from previous crashes. Pure bookkeeping
 				// against the _emdash_cron_tasks table — no request needs the
@@ -1444,45 +1634,9 @@ export class EmDashRuntime {
 				// cleanup-flag check costs an extra `options.get()` on every
 				// isolate cold boot forever. Cheaper to leave it.
 
-				// Auto-seed schema if no collections exist and setup hasn't run.
-				// This covers first-load on sites that skip the setup wizard.
-				// Dev-bypass and the wizard apply seeds explicitly.
-				try {
-					const [collectionCount, setupOption] = await Promise.all([
-						db
-							.selectFrom("_emdash_collections")
-							.select((eb) => eb.fn.countAll<number>().as("count"))
-							.executeTakeFirstOrThrow(),
-						db
-							.selectFrom("options")
-							.select("value")
-							.where("name", "=", "emdash:setup_complete")
-							.executeTakeFirst(),
-					]);
-
-					const setupDone = (() => {
-						try {
-							return setupOption && JSON.parse(setupOption.value) === true;
-						} catch {
-							return false;
-						}
-					})();
-
-					if (collectionCount.count === 0 && !setupDone) {
-						const { applySeed } = await import("./seed/apply.js");
-						const { loadSeed } = await import("./seed/load.js");
-						const { validateSeed } = await import("./seed/validate.js");
-
-						const seed = await loadSeed();
-						const validation = validateSeed(seed);
-						if (validation.valid) {
-							await applySeed(db, seed, { onConflict: "skip" });
-							console.log("Auto-seeded default collections");
-						}
-					}
-				} catch {
-					// Tables may not exist yet. Non-fatal.
-				}
+				// This returns a migrated but possibly unseeded db; create() runs
+				// the seed gate and applies the seed, batched with its other init
+				// reads.
 
 				// Publish only while still the current owner: a reclaimed slow
 				// init must not flip the cached Kysely identity back after the
@@ -2965,6 +3119,7 @@ export class EmDashRuntime {
 		if (trustedPlugin && this.enabledPlugins.has(trustedPlugin.id)) {
 			const routeRegistry = new PluginRouteRegistry({
 				db: this.db,
+				storage: this.storage ?? undefined,
 				emailPipeline: this.email ?? undefined,
 				trustedProxyHeaders: getTrustedProxyHeaders(this.config),
 			});

package/src/loader.ts

@@ -12,7 +12,7 @@
  */
 
 import type { LiveLoader } from "astro/loaders";
-import { Kysely, sql, type Dialect } from "kysely";
+import { Kysely, type RawBuilder, sql, type Dialect } from "kysely";
 
 import { currentTimestampValue, isPostgres } from "./database/dialect-helpers.js";
 import { kyselyLogOption } from "./database/instrumentation.js";
@@ -72,8 +72,83 @@ const SYSTEM_COLUMNS = new Set([
 	// fields. The aliases are _emdash_-prefixed so they can't shadow a user
 	// field named e.g. `seo_title`.
 	...SEO_ALIAS_COLUMNS,
+	// Folded hydration JSON columns (see foldedHydrationSelects) — surfaced via
+	// the FOLDED_* markers, never as flat fields.
+	"_emdash_terms",
+	"_emdash_bylines",
 ]);
 
+/** Markers for byline/taxonomy hydration folded into the content query. */
+export const FOLDED_TERMS = Symbol.for("emdash:foldedTerms");
+export const FOLDED_BYLINES = Symbol.for("emdash:foldedBylines");
+
+/**
+ * Correlated JSON-array subqueries that fold taxonomy-term and byline hydration
+ * into the content query, removing the two separate hydration round trips per
+ * fetch. `outer` is the content table's alias/name; each subquery correlates on
+ * `<outer>.id`, so the base query stays one row per entry (no join fan-out, no
+ * duplicated content payload). Order is NOT applied in the aggregate (it differs
+ * across dialects) — the consumer sorts terms by label and credits by sortOrder.
+ *
+ * Dialect-specific aggregation: SQLite `json_group_array`/`json_object` returns
+ * a JSON *string*; Postgres `json_agg`/`json_build_object` (coalesced to `[]`)
+ * returns parsed JSON. {@link stashFolded} handles both.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any Kysely instance
+function foldedHydrationSelects(db: Kysely<any>, type: string, outer: string) {
+	const o = sql.ref(outer);
+	const pg = isPostgres(db);
+	const obj = (pairs: string) =>
+		pg ? sql.raw(`json_build_object(${pairs})`) : sql.raw(`json_object(${pairs})`);
+	const agg = (inner: RawBuilder<unknown>) =>
+		pg ? sql`coalesce(json_agg(${inner}), '[]'::json)` : sql`json_group_array(${inner})`;
+
+	const termObj = obj(
+		"'id', t.id, 'name', t.name, 'slug', t.slug, 'label', t.label, 'parent_id', t.parent_id, 'locale', t.locale, 'translation_group', t.translation_group",
+	);
+	// Filter terms to the entry's own locale (matches #1441: terms render in the
+	// entry's resolved locale, not all locale variants of the attached group).
+	const terms = sql`(SELECT ${agg(termObj)} FROM ${sql.ref("content_taxonomies")} AS ct JOIN ${sql.ref("taxonomies")} AS t ON t.translation_group = ct.taxonomy_id WHERE ct.collection = ${type} AND ct.entry_id = ${o}.id AND t.locale = ${o}.locale) AS ${sql.ref("_emdash_terms")}`;
+
+	const bylineInner = obj(
+		"'id', b.id, 'slug', b.slug, 'displayName', b.display_name, 'bio', b.bio, 'avatarMediaId', b.avatar_media_id, 'avatarStorageKey', m.storage_key, 'avatarAlt', m.alt, 'avatarBlurhash', m.blurhash, 'avatarDominantColor', m.dominant_color, 'websiteUrl', b.website_url, 'userId', b.user_id, 'isGuest', b.is_guest, 'createdAt', b.created_at, 'updatedAt', b.updated_at, 'locale', b.locale, 'translationGroup', b.translation_group",
+	);
+	const creditObj = pg
+		? sql.raw(
+				"json_build_object('roleLabel', cb.role_label, 'sortOrder', cb.sort_order, 'byline', ",
+			)
+		: sql.raw("json_object('roleLabel', cb.role_label, 'sortOrder', cb.sort_order, 'byline', ");
+	const credit = sql`${creditObj}${bylineInner})`;
+	const bylines = sql`(SELECT ${agg(credit)} FROM ${sql.ref("_emdash_content_bylines")} AS cb JOIN ${sql.ref("_emdash_bylines")} AS b ON b.translation_group = cb.byline_id LEFT JOIN ${sql.ref("media")} AS m ON m.id = b.avatar_media_id WHERE cb.collection_slug = ${type} AND cb.content_id = ${o}.id AND b.locale = ${o}.locale) AS ${sql.ref("_emdash_bylines")}`;
+	return { terms, bylines };
+}
+
+/**
+ * Stash folded hydration JSON (non-enumerable) for the query.ts fast paths.
+ * SQLite returns a JSON string (parse it); Postgres returns already-parsed JSON.
+ */
+function stashFolded(data: Record<string, unknown>, row: Record<string, unknown>): void {
+	for (const [col, sym] of [
+		["_emdash_terms", FOLDED_TERMS],
+		["_emdash_bylines", FOLDED_BYLINES],
+	] as const) {
+		const raw = row[col];
+		let value: unknown;
+		if (typeof raw === "string") {
+			try {
+				value = JSON.parse(raw);
+			} catch {
+				continue; // malformed: fall back to the query path
+			}
+		} else if (Array.isArray(raw)) {
+			value = raw; // Postgres json/jsonb already parsed by the driver
+		} else {
+			continue;
+		}
+		Object.defineProperty(data, sym, { value, enumerable: false, configurable: true });
+	}
+}
+
 /** Resolved SEO shape attached to `entry.data.seo`. Mirrors `ContentSeo`. */
 interface EntrySeo {
 	title: string | null;
@@ -528,17 +603,17 @@ export interface WhereRange {
 export type WhereValue = string | string[] | WhereRange;
 
 /**
- * Filter for loadCollection - type is required
+ * Fields shared by every collection filter, independent of pagination mode.
+ *
+ * Cursor and offset pagination are mutually exclusive, so they live on the
+ * `CursorCollectionFilter` / `OffsetCollectionFilter` variants rather than
+ * here. Use the {@link CollectionFilter} union for any value that may be
+ * either.
  */
-export interface CollectionFilter {
+export interface CollectionFilterBase {
 	type: string;
 	status?: "draft" | "published" | "archived";
 	limit?: number;
-	/**
-	 * Opaque cursor for keyset pagination.
-	 * Pass the `nextCursor` value from a previous result to fetch the next page.
-	 */
-	cursor?: string;
 	/**
 	 * Filter by field values, taxonomy terms, byline credits, or ranges.
 	 *
@@ -566,6 +641,37 @@ export interface CollectionFilter {
 	locale?: string;
 }
 
+/** Keyset-paginated collection filter. Cannot also carry an `offset`. */
+export interface CursorCollectionFilter extends CollectionFilterBase {
+	/**
+	 * Opaque cursor for keyset pagination.
+	 * Pass the `nextCursor` value from a previous result to fetch the next page.
+	 */
+	cursor?: string;
+	offset?: never;
+}
+
+/** Offset-paginated collection filter. Cannot also carry a `cursor`. */
+export interface OffsetCollectionFilter extends CollectionFilterBase {
+	/**
+	 * Skip this many rows before returning results (offset pagination).
+	 * Use with `limit` for numbered archive routes (`/page/2`):
+	 * `offset = (page - 1) * perPage`. Ignored unless it is a positive
+	 * integer.
+	 */
+	offset?: number;
+	cursor?: never;
+}
+
+/**
+ * Filter for loadCollection - type is required.
+ *
+ * A union of the cursor and offset pagination variants: supplying both
+ * `cursor` and `offset` is a compile-time error, since they are mutually
+ * exclusive ways to express "the next page" (cursor wins at runtime).
+ */
+export type CollectionFilter = CursorCollectionFilter | OffsetCollectionFilter;
+
 /**
  * Filter for loadEntry - type and id are required
  */
@@ -675,6 +781,17 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				// Cursor pagination: over-fetch by 1 to detect next page
 				const fetchLimit = limit ? limit + 1 : undefined;
 
+				// Offset pagination (numbered archive routes). Keyset (cursor)
+				// and offset are mutually exclusive ways to express "the next
+				// page" — when both are supplied, cursor wins and offset is
+				// dropped so the two don't stack into a double skip. Only a
+				// positive integer applies; 0 / negative / fractional are no-ops.
+				const rawOffset = cursor ? undefined : filter?.offset;
+				const offset =
+					typeof rawOffset === "number" && Number.isInteger(rawOffset) && rawOffset > 0
+						? rawOffset
+						: undefined;
+
 				// Build cursor condition if cursor is provided
 				const cursorCondition = cursor ? buildCursorCondition(cursor, orderBy) : null;
 
@@ -785,8 +902,28 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 						)`
 						: sql``;
 
+					// Fold byline + taxonomy hydration into the list query.
+					const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
+						db,
+						type,
+						tableName,
+					);
+
+					// LIMIT/OFFSET clause. SQLite only accepts OFFSET when a
+					// LIMIT is present, so a bare offset uses `LIMIT -1`
+					// (unbounded); Postgres takes a standalone OFFSET.
+					let limitOffsetClause = sql``;
+					if (fetchLimit != null && offset != null) {
+						limitOffsetClause = sql`LIMIT ${fetchLimit} OFFSET ${offset}`;
+					} else if (fetchLimit != null) {
+						limitOffsetClause = sql`LIMIT ${fetchLimit}`;
+					} else if (offset != null) {
+						limitOffsetClause = isPostgres(db)
+							? sql`OFFSET ${offset}`
+							: sql`LIMIT -1 OFFSET ${offset}`;
+					}
 					result = await sql<Record<string, unknown>>`
-						SELECT * FROM ${sql.ref(tableName)}
+						SELECT *, ${termsSelect}, ${bylinesSelect} FROM ${sql.ref(tableName)}
 						WHERE deleted_at IS NULL
 						AND ${statusCondition}
 						${localeFilter}
@@ -795,7 +932,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 						${bylineCond}
 						${fieldCondsSQL ? sql`AND ${fieldCondsSQL}` : sql``}
 						${orderByClause}
-						${fetchLimit ? sql`LIMIT ${fetchLimit}` : sql``}
+						${limitOffsetClause}
 					`.execute(db);
 				}
 
@@ -814,11 +951,13 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 						rowLocale !== "" &&
 						(rowLocale !== i18nConfig.defaultLocale || i18nConfig.prefixDefaultLocale);
 					const id = shouldPrefix ? `${rowLocale}/${slug}` : slug;
+					const data = mapRowToData(row);
+					stashFolded(data, row);
 					return {
 						id,
 						slug: rowStr(row, "slug"),
 						status: rowStr(row, "status", "draft"),
-						data: mapRowToData(row),
+						data,
 						cacheHint: {
 							tags: [rowStr(row, "id")],
 							lastModified: row.updated_at ? new Date(rowStr(row, "updated_at")) : undefined,
@@ -922,9 +1061,17 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 						([col, alias]) => sql`${sql.ref(`s.${col}`)} AS ${sql.ref(alias)}`,
 					),
 				);
+				// Fold byline + taxonomy hydration into the content query (see
+				// foldedHydrationSelects), removing the two separate hydration
+				// round trips per fetch.
+				const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
+					db,
+					type,
+					"c",
+				);
 				const result = locale
 					? await sql<Record<string, unknown>>`
-							SELECT c.*, ${seoSelect}
+							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
 							FROM ${sql.ref(tableName)} AS c
 							LEFT JOIN ${sql.ref("_emdash_seo")} AS s
 								ON s.collection = ${type} AND s.content_id = c.id
@@ -933,7 +1080,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 							LIMIT 1
 						`.execute(db)
 					: await sql<Record<string, unknown>>`
-							SELECT c.*, ${seoSelect}
+							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
 							FROM ${sql.ref(tableName)} AS c
 							LEFT JOIN ${sql.ref("_emdash_seo")} AS s
 								ON s.collection = ${type} AND s.content_id = c.id
@@ -1015,6 +1162,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				const entryData = mapRowToData(row);
 				const entrySeo = extractSeo(row);
 				if (entrySeo) entryData.seo = entrySeo;
+				stashFolded(entryData, row);
 				return {
 					id: entryId,
 					slug: rowStr(row, "slug"),