emdash 0.28.1 → 0.29.0

package/src/database/repositories/content.ts

@@ -2,6 +2,9 @@ import { sql, type Kysely } from "kysely";
 import { ulid } from "ulidx";
 
 import { invalidateCollectionCache } from "../../object-cache/index.js";
+import { buildFtsPrefixMatch, buildSlugGlobPrefix } from "../../search/match.js";
+import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
+import { isMissingTableError } from "../../utils/db-errors.js";
 import { slugify } from "../../utils/slugify.js";
 import type { Database } from "../types.js";
 import { validateIdentifier } from "../validate.js";
@@ -402,16 +405,26 @@ export class ContentRepository {
 			? (t: string, s: string) => this.findBySlugIncludingTrashed(t, s, locale)
 			: (t: string, s: string) => this.findBySlug(t, s, locale);
 
-		if (looksLikeUlid) {
-			// Try ID first, fall back to slug
-			const byId = await findById(type, identifier);
-			if (byId) return byId;
-			return findBySlug(type, identifier);
+		try {
+			if (looksLikeUlid) {
+				// Try ID first, fall back to slug
+				const byId = await findById(type, identifier);
+				if (byId) return byId;
+				return await findBySlug(type, identifier);
+			}
+			// Try slug first, fall back to ID
+			const bySlug = await findBySlug(type, identifier);
+			if (bySlug) return bySlug;
+			return await findById(type, identifier);
+		} catch (error) {
+			// A collection dropped out from under a still-referencing caller (e.g. a
+			// relation whose collection was deleted without cascading) leaves the
+			// ec_* table missing. Treat that as "not found", matching
+			// findManyByIdOrSlug and findTranslationsForGroups, so callers surface a
+			// structured NOT_FOUND instead of a 500.
+			if (isMissingTableError(error)) return null;
+			throw error;
 		}
-		// Try slug first, fall back to ID
-		const bySlug = await findBySlug(type, identifier);
-		if (bySlug) return bySlug;
-		return findById(type, identifier);
 	}
 
 	/**
@@ -513,7 +526,7 @@ export class ContentRepository {
 			query = query.where("locale" as any, "=", options.where.locale);
 		}
 
-		query = this.applySearchFilter(query, options.where);
+		query = this.applySearchFilter(query, options.where, type);
 		query = this.applyDateFilter(query, options.where);
 
 		// Handle cursor pagination — decodeCursor throws InvalidCursorError
@@ -792,19 +805,46 @@ export class ContentRepository {
 	}
 
 	/**
-	 * Apply the optional case-insensitive `q` substring filter across the
-	 * handler-resolved `searchColumns` (OR'd). User input is treated literally
-	 * (LIKE wildcards escaped) and `lower()` is applied on both sides for
-	 * SQLite/Postgres case-insensitive parity.
+	 * Apply the optional `q` filter.
+	 *
+	 * When the handler sets `useFts` (collection has a healthy FTS5 index
+	 * covering the display columns; SQLite only), the filter is served from
+	 * the index: a token-prefix MATCH against `_emdash_fts_<slug>` OR'd with
+	 * an index-served `slug GLOB 'term*'` prefix (the slug is not in the FTS
+	 * index). Both sides are index-backed, so SQLite's OR optimization avoids
+	 * the full-table scan the LIKE fallback needs (#1517). The trade-off is
+	 * search semantics: token-prefix matching instead of arbitrary substring.
+	 *
+	 * Fallback (Postgres, search disabled, or no usable terms): case-
+	 * insensitive substring LIKE across the handler-resolved `searchColumns`
+	 * (OR'd). User input is treated literally (LIKE wildcards escaped) and
+	 * `lower()` is applied on both sides for SQLite/Postgres parity.
 	 */
 	private applySearchFilter<QB extends { where: (cb: (eb: any) => unknown) => QB }>(
 		query: QB,
-		where?: { q?: string; searchColumns?: string[] },
+		where: { q?: string; searchColumns?: string[]; useFts?: boolean } | undefined,
+		type: string,
 	): QB {
 		const term = where?.q?.trim();
 		const columns = where?.searchColumns;
 		if (!term || !columns || columns.length === 0) return query;
 
+		if (where.useFts) {
+			const match = buildFtsPrefixMatch(term);
+			if (match) {
+				validateIdentifier(type, "collection slug");
+				const ftsTable = `_emdash_fts_${type}`;
+				const slugPrefix = buildSlugGlobPrefix(term);
+				return query.where((eb) =>
+					eb.or([
+						sql<boolean>`id IN (SELECT id FROM ${sql.ref(ftsTable)} WHERE ${sql.ref(ftsTable)} MATCH ${match})`,
+						sql<boolean>`slug GLOB ${slugPrefix}`,
+					]),
+				);
+			}
+			// No usable terms (e.g. quotes only) — fall through to LIKE.
+		}
+
 		const escaped = term.replace(LIKE_WILDCARD_RE, (c) => `\\${c}`);
 		const pattern = `%${escaped}%`;
 
@@ -866,7 +906,7 @@ export class ContentRepository {
 			query = query.where("locale" as any, "=", where.locale);
 		}
 
-		query = this.applySearchFilter(query, where);
+		query = this.applySearchFilter(query, where, type);
 		query = this.applyDateFilter(query, where);
 
 		const result = await query.executeTakeFirst();
@@ -890,13 +930,13 @@ export class ContentRepository {
 			.where("author_id" as never, "is not", null)
 			.execute();
 
-		return rows
-			.map((row) => (row as { author_id: string | null }).author_id)
-			.filter((id): id is string => id !== null);
+		return rows.map((row) => row.author_id).filter((id): id is string => id !== null);
 	}
 
-	// get overall statistics (total, published, draft) for a content type in a single query
-	async getStats(type: string): Promise<{ total: number; published: number; draft: number }> {
+	// get overall statistics for a content type in a single query
+	async getStats(
+		type: string,
+	): Promise<{ total: number; published: number; draft: number; scheduled: number }> {
 		const tableName = getTableName(type);
 
 		const result = await this.db
@@ -905,6 +945,7 @@ export class ContentRepository {
 				eb.fn.count("id").as("total"),
 				eb.fn.sum(eb.case().when("status", "=", "published").then(1).else(0).end()).as("published"),
 				eb.fn.sum(eb.case().when("status", "=", "draft").then(1).else(0).end()).as("draft"),
+				sql<number>`SUM(CASE WHEN scheduled_at IS NOT NULL THEN 1 ELSE 0 END)`.as("scheduled"),
 			])
 			.where("deleted_at" as never, "is", null)
 			.executeTakeFirst();
@@ -913,6 +954,7 @@ export class ContentRepository {
 			total: Number(result?.total || 0),
 			published: Number(result?.published || 0),
 			draft: Number(result?.draft || 0),
+			scheduled: Number(result?.scheduled || 0),
 		};
 	}
 
@@ -1054,6 +1096,115 @@ export class ContentRepository {
 		return result.rows.map((row) => this.mapRow(type, row));
 	}
 
+	/**
+	 * Batch variant of {@link findTranslations}: every (non-deleted) locale
+	 * variant for any of `translationGroups`, in one `WHERE translation_group IN
+	 * (...)` query chunked at `SQL_BATCH_SIZE` for D1's bind-parameter limit.
+	 * Lets callers resolve many edge groups without an N+1 per group. The caller
+	 * groups the flat result by `translationGroup` itself.
+	 *
+	 * `publishedOnly` restricts the result to `status = 'published'` — reference
+	 * reads pass this for callers without `content:read_drafts` so draft/scheduled
+	 * entries never leak through an edge traversal.
+	 *
+	 * A reference edge stores only a collection slug (no SQL FK), so the table may
+	 * have been dropped since the edge was written. That is a tolerated dangling
+	 * state, not an error: a missing table resolves to no rows, mirroring how the
+	 * content read handlers treat `isMissingTableError`.
+	 */
+	async findTranslationsForGroups(
+		type: string,
+		translationGroups: string[],
+		options: { publishedOnly?: boolean } = {},
+	): Promise<ContentItem[]> {
+		if (translationGroups.length === 0) return [];
+		const tableName = getTableName(type);
+		const publishedFilter = options.publishedOnly ? sql`AND status = 'published'` : sql``;
+
+		const items: ContentItem[] = [];
+		try {
+			for (const chunk of chunks(translationGroups, SQL_BATCH_SIZE)) {
+				const result = await sql<Record<string, unknown>>`
+					SELECT * FROM ${sql.ref(tableName)}
+					WHERE translation_group IN (${sql.join(chunk)})
+					AND deleted_at IS NULL
+					${publishedFilter}
+					ORDER BY locale ASC
+				`.execute(this.db);
+				for (const row of result.rows) items.push(this.mapRow(type, row));
+			}
+		} catch (error) {
+			if (isMissingTableError(error)) return [];
+			throw error;
+		}
+		return items;
+	}
+
+	/**
+	 * Batch variant of {@link findByIdOrSlug}: resolve many identifiers (each an
+	 * id OR a slug) within `type` in a constant number of queries — one `WHERE id
+	 * IN (...)` and one `WHERE slug IN (...)`, each chunked at `SQL_BATCH_SIZE`.
+	 * Returns a map from the input identifier to its resolved item; identifiers
+	 * that match nothing are absent. Used on write paths that accept a list of
+	 * references, so a single request doesn't fan out to an N+1 of point lookups.
+	 *
+	 * Resolution mirrors {@link findByIdOrSlug}: a ULID-shaped identifier prefers
+	 * the id match and falls back to slug; anything else prefers the slug match
+	 * and falls back to id. Slug matches collapse to the lowest-locale variant
+	 * (`ORDER BY locale ASC`), matching the slug-without-locale lookup.
+	 */
+	async findManyByIdOrSlug(type: string, identifiers: string[]): Promise<Map<string, ContentItem>> {
+		const resolved = new Map<string, ContentItem>();
+		const unique = [...new Set(identifiers)];
+		if (unique.length === 0) return resolved;
+
+		const tableName = getTableName(type);
+		const byId = new Map<string, ContentItem>();
+		const bySlug = new Map<string, ContentItem>();
+
+		try {
+			for (const chunk of chunks(unique, SQL_BATCH_SIZE)) {
+				const idRows = await sql<Record<string, unknown>>`
+					SELECT * FROM ${sql.ref(tableName)}
+					WHERE id IN (${sql.join(chunk)})
+					AND deleted_at IS NULL
+				`.execute(this.db);
+				for (const row of idRows.rows) {
+					const item = this.mapRow(type, row);
+					byId.set(item.id, item);
+				}
+
+				const slugRows = await sql<Record<string, unknown>>`
+					SELECT * FROM ${sql.ref(tableName)}
+					WHERE slug IN (${sql.join(chunk)})
+					AND deleted_at IS NULL
+					ORDER BY locale ASC
+				`.execute(this.db);
+				for (const row of slugRows.rows) {
+					const item = this.mapRow(type, row);
+					// First write wins → lowest locale, matching findBySlug without a locale.
+					if (item.slug != null && !bySlug.has(item.slug)) bySlug.set(item.slug, item);
+				}
+			}
+		} catch (error) {
+			// A collection dropped after a relation was created leaves the relation
+			// pointing at a missing table. Treat it like an empty collection (no
+			// matches) so callers surface a structured NOT_FOUND, not a 500 —
+			// mirroring findTranslationsForGroups.
+			if (isMissingTableError(error)) return resolved;
+			throw error;
+		}
+
+		for (const identifier of unique) {
+			const looksLikeUlid = ULID_PATTERN.test(identifier);
+			const item = looksLikeUlid
+				? (byId.get(identifier) ?? bySlug.get(identifier))
+				: (bySlug.get(identifier) ?? byId.get(identifier));
+			if (item) resolved.set(identifier, item);
+		}
+		return resolved;
+	}
+
 	/**
 	 * Publish the current draft
 	 *

package/src/database/repositories/media.ts

@@ -118,7 +118,7 @@ export class MediaRepository {
 
 		await this.db.insertInto("media").values(row).execute();
 
-		return this.rowToItem(row as MediaRow);
+		return this.rowToItem(row);
 	}
 
 	/**

package/src/database/repositories/relation.ts

@@ -3,6 +3,7 @@ import { ulid } from "ulidx";
 
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import type { Database, RelationTable, ContentReferenceTable } from "../types.js";
+import { decodeCursor, encodeCursor, InvalidCursorError, type FindManyResult } from "./types.js";
 
 export interface Relation {
 	id: string;
@@ -17,8 +18,12 @@ export interface Relation {
 
 export interface CreateRelationInput {
 	name: string;
-	parentCollection: string;
-	childCollection: string;
+	/** Required for a base relation; ignored (inherited from the source) when
+	 * `translationOf` is set. */
+	parentCollection?: string;
+	/** Required for a base relation; ignored (inherited from the source) when
+	 * `translationOf` is set. */
+	childCollection?: string;
 	parentLabel: string;
 	childLabel: string;
 	/** Omit to let the DB default (current value: 'en') apply. Higher layers
@@ -73,9 +78,9 @@ export class RelationRepository {
 		const now = new Date().toISOString();
 
 		let translationGroup = id;
-		let name = input.name;
-		let parentCollection = input.parentCollection;
-		let childCollection = input.childCollection;
+		let name: string;
+		let parentCollection: string;
+		let childCollection: string;
 
 		if (input.translationOf) {
 			const source = await this.findById(input.translationOf);
@@ -87,6 +92,18 @@ export class RelationRepository {
 			name = source.name;
 			parentCollection = source.parentCollection;
 			childCollection = source.childCollection;
+		} else {
+			// A base relation carries its own structural fields. The API layer's Zod
+			// schema enforces this; guard here too since the repo trusts its inputs
+			// and the columns are NOT NULL.
+			if (input.parentCollection === undefined || input.childCollection === undefined) {
+				throw new Error(
+					"parentCollection and childCollection are required unless translationOf is set",
+				);
+			}
+			name = input.name;
+			parentCollection = input.parentCollection;
+			childCollection = input.childCollection;
 		}
 
 		await this.db
@@ -319,6 +336,61 @@ export class RelationRepository {
 		return rows.map((row) => this.rowToReference(row));
 	}
 
+	/**
+	 * Forward traversal, paginated: one page of a parent's children for a
+	 * relation, ordered by `(sort_order, id)`. Use this on request paths — a
+	 * parent's children are capped but still up to 1000, and an unbounded read
+	 * scales poorly. Returns `{ items, nextCursor? }`; the cursor's order value is
+	 * the row's `sort_order`. Default limit 50, max 100.
+	 */
+	async getChildrenPage(
+		relation: string,
+		parentGroup: string,
+		options: { limit?: number; cursor?: string } = {},
+	): Promise<FindManyResult<ContentReference>> {
+		const relationGroup = await this.resolveRelationGroup(relation);
+		if (!relationGroup) return { items: [] };
+
+		const limit = Math.min(options.limit || 50, 100);
+
+		let query = this.db
+			.selectFrom("_emdash_content_references")
+			.selectAll()
+			.where("relation_group", "=", relationGroup)
+			.where("parent_group", "=", parentGroup);
+
+		if (options.cursor) {
+			const decoded = decodeCursor(options.cursor);
+			const sortOrder = Number(decoded.orderValue);
+			// `decodeCursor` only guarantees `orderValue` is a string; a hand-crafted
+			// cursor with a non-numeric order value would coerce to NaN and blow up at
+			// the driver bind as a 500. A bad cursor is a client error — surface it as
+			// INVALID_CURSOR (400). Server-issued cursors are always numeric here.
+			if (!Number.isFinite(sortOrder)) throw new InvalidCursorError(options.cursor);
+			query = query.where((eb) =>
+				eb.or([
+					eb("sort_order", ">", sortOrder),
+					eb.and([eb("sort_order", "=", sortOrder), eb("id", ">", decoded.id)]),
+				]),
+			);
+		}
+
+		const rows = await query
+			.orderBy("sort_order", "asc")
+			.orderBy("id", "asc")
+			.limit(limit + 1)
+			.execute();
+
+		const hasMore = rows.length > limit;
+		const items = rows.slice(0, limit).map((row) => this.rowToReference(row));
+		const result: FindManyResult<ContentReference> = { items };
+		const last = items.at(-1);
+		if (hasMore && last) {
+			result.nextCursor = encodeCursor(String(last.sortOrder), last.id);
+		}
+		return result;
+	}
+
 	/** Backlink traversal: the parents that reference a child for a relation. */
 	async getParents(relation: string, childGroup: string): Promise<ContentReference[]> {
 		const relationGroup = await this.resolveRelationGroup(relation);
@@ -346,6 +418,15 @@ export class RelationRepository {
 	 * relying on the insert's onConflict to silently drop them. Not wrapped in a
 	 * transaction: a crash between the delete and insert leaves the parent with
 	 * no children — acceptable for a replace-all, since a retry restores state.
+	 *
+	 * Concurrency: two simultaneous replace-all calls for the same (relation,
+	 * parent) can interleave their deletes and inserts and merge into the union of
+	 * both sets (a lost update — neither "replace" wins). This is non-corrupting —
+	 * keyset pagination stays totally ordered via the `(sort_order, id)` tiebreak
+	 * even with duplicate sort_orders — and a single client editing one parent's
+	 * children serially never hits it. A D1-portable fix isn't available (no
+	 * multi-statement transactions), so concurrent replace-all on one parent is
+	 * unsupported by design rather than guarded here.
 	 */
 	async setChildren(relation: string, parentGroup: string, childGroups: string[]): Promise<void> {
 		const relationGroup = await this.resolveRelationGroup(relation);
@@ -381,6 +462,50 @@ export class RelationRepository {
 			.execute();
 	}
 
+	/**
+	 * Backlink traversal, paginated: one page of the parents that reference a
+	 * child for a relation, ordered by `id`. Unlike a parent's children, a
+	 * child's backlinks are *unbounded* — one popular entry can be referenced by
+	 * arbitrarily many parents — so this read must paginate. Returns
+	 * `{ items, nextCursor? }`; the cursor's order value is the row `id`. Default
+	 * limit 50, max 100.
+	 */
+	async getParentsPage(
+		relation: string,
+		childGroup: string,
+		options: { limit?: number; cursor?: string } = {},
+	): Promise<FindManyResult<ContentReference>> {
+		const relationGroup = await this.resolveRelationGroup(relation);
+		if (!relationGroup) return { items: [] };
+
+		const limit = Math.min(options.limit || 50, 100);
+
+		let query = this.db
+			.selectFrom("_emdash_content_references")
+			.selectAll()
+			.where("relation_group", "=", relationGroup)
+			.where("child_group", "=", childGroup);
+
+		if (options.cursor) {
+			const decoded = decodeCursor(options.cursor);
+			query = query.where("id", ">", decoded.id);
+		}
+
+		const rows = await query
+			.orderBy("id", "asc")
+			.limit(limit + 1)
+			.execute();
+
+		const hasMore = rows.length > limit;
+		const items = rows.slice(0, limit).map((row) => this.rowToReference(row));
+		const result: FindManyResult<ContentReference> = { items };
+		const last = items.at(-1);
+		if (hasMore && last) {
+			result.nextCursor = encodeCursor(last.id, last.id);
+		}
+		return result;
+	}
+
 	/**
 	 * Remove every edge where `group` is the parent OR the child — i.e. ensure no
 	 * orphaned reference edges survive when a content entry is deleted. The

package/src/database/repositories/taxonomy.ts

@@ -404,6 +404,12 @@ export class TaxonomyRepository {
 	/**
 	 * Count content entries that use any translation of this term. Accepts
 	 * either a term id or a translation_group — we normalise to the group.
+	 *
+	 * Counts raw pivot rows regardless of the entry's status or deletion —
+	 * drafts and trashed entries are included. User-facing counts (admin term
+	 * list/get, public widget and term pages) use `fetchVisibleTermCounts`
+	 * from `taxonomies/term-counts.ts` instead, which counts only publicly
+	 * visible entries.
 	 */
 	async countEntriesWithTerm(termIdOrGroup: string): Promise<number> {
 		const group = await this.resolveTranslationGroup(termIdOrGroup);
@@ -453,6 +459,9 @@ export class TaxonomyRepository {
 	 *
 	 * Pass translation_groups (not term ids) — `content_taxonomies.taxonomy_id`
 	 * stores the translation_group so a single assignment spans every locale.
+	 *
+	 * Like `countEntriesWithTerm`, this counts raw pivot rows regardless of
+	 * status/deletion; user-facing counts go through `fetchVisibleTermCounts`.
 	 */
 	async countEntriesForTerms(translationGroups: string[]): Promise<Map<string, number>> {
 		if (translationGroups.length === 0) return new Map();

package/src/database/repositories/types.ts

@@ -158,6 +158,14 @@ export interface FindManyOptions {
 		 * repository stays generic. Each name is validated as a SQL identifier.
 		 */
 		searchColumns?: string[];
+		/**
+		 * Serve `q` from the collection's FTS5 index (`_emdash_fts_<slug>`)
+		 * instead of an unindexable substring LIKE. Set by the handler only
+		 * when the collection has search enabled and the index exists
+		 * (SQLite only). The repository combines a token-prefix MATCH with
+		 * an index-served slug prefix so slug lookups keep working.
+		 */
+		useFts?: boolean;
 		/** Inclusive date range over a whitelisted timestamp column. */
 		dateFilter?: ContentDateFilter;
 	};

package/src/db/postgres.ts

@@ -5,9 +5,10 @@
  * Loaded at runtime via virtual module.
  */
 
-import { PostgresDialect } from "kysely";
+import type { PostgresDialect } from "kysely";
 import { Pool } from "pg";
 
+import { FailFastPostgresDialect } from "../database/pg-migration-lock.js";
 import type { PostgresConfig } from "./adapters.js";
 
 /**
@@ -26,5 +27,7 @@ export function createDialect(config: PostgresConfig): PostgresDialect {
 		max: config.pool?.max ?? 10,
 	});
 
-	return new PostgresDialect({ pool });
+	// Fail-fast migration locking instead of Kysely's blocking advisory
+	// lock — see pg-migration-lock.ts (#1744).
+	return new FailFastPostgresDialect({ pool });
 }

package/src/emdash-runtime.ts

@@ -22,7 +22,11 @@ import { getAuthMode } from "./auth/mode.js";
 import { getTrustedProxyHeaders } from "./auth/trusted-proxy.js";
 import { isSqlite } from "./database/dialect-helpers.js";
 import { kyselyLogOption } from "./database/instrumentation.js";
-import { MIGRATION_RACE_WAIT_MS, runMigrations } from "./database/migrations/runner.js";
+import {
+	ConcurrentMigrationTimeoutError,
+	MIGRATION_RACE_WAIT_MS,
+	runMigrations,
+} from "./database/migrations/runner.js";
 import { RevisionRepository } from "./database/repositories/revision.js";
 import type {
 	ContentItem as ContentItemInternal,
@@ -385,18 +389,42 @@ const DB_HOLDER_KEY = Symbol.for("emdash:db-cache");
 interface DbHolder {
 	cache: Map<string, Kysely<Database>>;
 	lock: InitLock;
+	/**
+	 * Recent migration failures, keyed like `cache`. A failed migration is
+	 * near-certain to fail again immediately (schema conflict, broken
+	 * migration), and without this every request in a warm isolate would
+	 * re-attempt it — on Workers with Postgres that stampedes the database
+	 * through the migration advisory lock (#1744). Entries expire after
+	 * DB_INIT_FAILURE_BACKOFF_MS; a successful init clears them.
+	 */
+	failures: Map<string, { at: number; message: string }>;
 }
 const globalSymbolStore = globalThis as Record<symbol, unknown>;
 function getDbHolder(): DbHolder {
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis symbol slot, written only below
 	let holder = globalSymbolStore[DB_HOLDER_KEY] as DbHolder | undefined;
 	if (!holder) {
-		holder = { cache: new Map<string, Kysely<Database>>(), lock: createInitLock() };
+		holder = {
+			cache: new Map<string, Kysely<Database>>(),
+			lock: createInitLock(),
+			failures: new Map(),
+		};
 		globalSymbolStore[DB_HOLDER_KEY] = holder;
 	}
+	// A holder created by an older copy of this module (dev-server HMR keeps
+	// globalThis across reloads) may predate the failures map.
+	holder.failures ??= new Map();
 	return holder;
 }
 
+/**
+ * After a database init fails (migrations threw), skip re-attempting for
+ * this long. Cold isolates still get one attempt each, so a transient
+ * failure heals on its own; a persistently failing migration is retried at
+ * most once per backoff window per isolate instead of on every request.
+ */
+const DB_INIT_FAILURE_BACKOFF_MS = 30_000;
+
 /**
  * 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
@@ -1623,14 +1651,52 @@ export class EmDashRuntime {
 		// owner's init still completes and populates the cache. Net: a stale
 		// lock is reclaimed after a deadline.
 		const holder = getDbHolder();
+
+		const throwIfBackingOff = () => {
+			const failure = holder.failures.get(cacheKey);
+			if (!failure) return;
+			if (Date.now() - failure.at < DB_INIT_FAILURE_BACKOFF_MS) {
+				throw new Error(
+					`Database initialization is backing off after a recent migration failure: ${failure.message}`,
+				);
+			}
+			// Expired — drop it so the map only ever holds active backoffs.
+			holder.failures.delete(cacheKey);
+		};
+		throwIfBackingOff();
+
 		return initWithLock(
 			holder.lock,
 			() => holder.cache.get(cacheKey),
 			async (isCurrentClaim) => {
+				// Re-check under the lock: a request that entered the wait loop
+				// before the failure was recorded must not immediately re-run
+				// the failing migration when the lock frees up.
+				throwIfBackingOff();
+
 				const dialect = deps.createDialect(dbConfig.config);
 				const db = new Kysely<Database>({ dialect, log: kyselyLogOption() });
 
-				await runMigrations(db);
+				try {
+					await runMigrations(db);
+				} catch (error) {
+					// Timing out behind another instance's in-flight migrations
+					// is not a failure of OUR migration — the holder may just be
+					// slow. Don't back off for it: the next request waits again
+					// and init recovers the moment the holder finishes.
+					if (!(error instanceof ConcurrentMigrationTimeoutError)) {
+						holder.failures.set(cacheKey, {
+							at: Date.now(),
+							message: error instanceof Error ? error.message : String(error),
+						});
+					}
+					// Every attempt builds a fresh dialect/pool; close it or each
+					// failed init leaks its connection(s) (#1744 observed these
+					// piling up as idle Postgres connections).
+					await db.destroy().catch(() => {});
+					throw error;
+				}
+				holder.failures.delete(cacheKey);
 
 				// Note: legacy installs may carry a stray `emdash:manifest_cache`
 				// row in the options table from versions that persisted a JSON
@@ -2520,7 +2586,7 @@ export class EmDashRuntime {
 					...r.data,
 					item: { ...item, data: mergedData, liveData },
 				},
-			} as T;
+			};
 		} catch (error) {
 			// Non-fatal — fall back to the unhydrated response. Log so the
 			// failure isn't completely silent (the response will look stale
@@ -2540,6 +2606,7 @@ export class EmDashRuntime {
 			bylines?: Array<{ bylineId: string; roleLabel?: string | null }>;
 			locale?: string;
 			translationOf?: string;
+			taxonomies?: Record<string, string[]>;
 		},
 	) {
 		// Run beforeSave hooks (trusted plugins)
@@ -2604,6 +2671,7 @@ export class EmDashRuntime {
 				canonical?: string | null;
 				noIndex?: boolean;
 			};
+			taxonomies?: Record<string, string[]>;
 			publishedAt?: string | null;
 			locale?: string;
 			/** Skip revision creation (used by autosave) */

package/src/index.ts

@@ -247,6 +247,10 @@ export type {
 	MediaAccess,
 	HttpAccess,
 	LogAccess,
+	TaxonomyAccess,
+	TaxonomyDefInfo,
+	TaxonomyTermInfo,
+	TaxonomyReadOptions,
 	PluginHooks,
 	HookConfig,
 	HookName,
@@ -404,8 +408,8 @@ export type {
 } from "./settings/types.js";
 
 // SEO
-export { getSeoMeta, getContentSeo } from "./seo/index.js";
-export type { SeoMeta, SeoMetaOptions } from "./seo/index.js";
+export { getSeoMeta, getContentSeo, getHreflangAlternates } from "./seo/index.js";
+export type { SeoMeta, SeoMetaOptions, HreflangAlternate, HreflangOptions } from "./seo/index.js";
 
 // Public page contribution types
 export type {