emdash 0.28.1 → 0.30.0

package/src/components/PortableText.astro

@@ -22,6 +22,7 @@ import { getEditMeta } from "../query.js";
 import { pluginBlockComponents } from "virtual:emdash/block-components";
 import { emdashComponents } from "./index.js";
 import InlineEditor from "./InlineEditor.astro";
+import { groupBlockquoteRuns } from "./portable-text-blockquote-group.js";
 
 export interface Props extends Omit<PortableTextProps, "value"> {
 	value: PortableTextProps["value"];
@@ -37,6 +38,11 @@ const withPlugins = mergeComponents(emdashComponents, { type: pluginBlockCompone
 const mergedComponents = userComponents
 	? mergeComponents(withPlugins, userComponents)
 	: withPlugins;
+
+// A multi-paragraph quote is stored as consecutive blockquote-styled blocks
+// (Portable Text is flat); merge each run into one blockquoteGroup node so
+// it renders as a single <blockquote> instead of several (#1884).
+const renderValue = Array.isArray(value) ? groupBlockquoteRuns(value) : value;
 ---
 
 {editMeta ? (
@@ -47,5 +53,5 @@ const mergedComponents = userComponents
 		field={editMeta.field}
 	/>
 ) : (
-	<BasePortableText value={value} components={mergedComponents} {...rest} />
+	<BasePortableText value={renderValue} components={mergedComponents} {...rest} />
 )}

package/src/components/index.ts

@@ -59,6 +59,7 @@ export { default as StrikeThrough } from "./marks/StrikeThrough.astro";
 export { default as Link } from "./marks/Link.astro";
 
 import BlockComponent from "./Block.astro";
+import BlockquoteGroupComponent from "./BlockquoteGroup.astro";
 import BreakComponent from "./Break.astro";
 import ButtonComponent from "./Button.astro";
 import ButtonsComponent from "./Buttons.astro";
@@ -88,6 +89,7 @@ import TableComponent from "./Table.astro";
 export const emdashComponents = {
 	block: BlockComponent,
 	type: {
+		blockquoteGroup: BlockquoteGroupComponent,
 		image: ImageComponent,
 		code: CodeComponent,
 		embed: EmbedComponent,

package/src/components/marks/Link.astro

@@ -19,7 +19,11 @@ export interface Props {
 
 const { node } = Astro.props;
 const href = sanitizeHref(node?.markDef?.href);
-const blank = node?.markDef?.blank;
+// Same-page anchor links (`#section`) are on-page jumps — opening them in a
+// new tab is never desirable, so force same-tab regardless of the mark's
+// `blank` flag.
+const isSamePageAnchor = href.startsWith("#");
+const blank = !isSamePageAnchor && node?.markDef?.blank;
 ---
 
 <a

package/src/components/portable-text-blockquote-group.ts

@@ -0,0 +1,68 @@
+/**
+ * Groups consecutive Portable Text blocks with style "blockquote" into a
+ * single synthetic `blockquoteGroup` node so they render as ONE
+ * `<blockquote>` with a paragraph per block.
+ *
+ * Portable Text is flat: a multi-paragraph quote (e.g. from a WordPress
+ * `core/quote` import) is stored as consecutive blocks with
+ * `style: "blockquote"`. Rendering each of those as its own `<blockquote>`
+ * visually splits the quote (#1884).
+ *
+ * Runs of a single block are left untouched, so existing single-paragraph
+ * quotes render byte-for-byte as before.
+ */
+
+interface TextBlockLike {
+	_type: string;
+	_key?: string;
+	style?: string;
+	listItem?: string;
+}
+
+export interface BlockquoteGroupNode {
+	_type: "blockquoteGroup";
+	_key: string;
+	blocks: TextBlockLike[];
+}
+
+function isBlockquoteBlock(block: unknown): block is TextBlockLike {
+	if (typeof block !== "object" || block === null) return false;
+	const b: Partial<TextBlockLike> = block;
+	// Quote-styled list items belong to their list, not to a quote run.
+	return b._type === "block" && b.style === "blockquote" && b.listItem === undefined;
+}
+
+export function groupBlockquoteRuns(blocks: unknown[]): unknown[] {
+	const result: unknown[] = [];
+	let i = 0;
+
+	while (i < blocks.length) {
+		const current = blocks[i];
+		if (!isBlockquoteBlock(current)) {
+			result.push(current);
+			i++;
+			continue;
+		}
+
+		const run: TextBlockLike[] = [];
+		let next: unknown = current;
+		while (i < blocks.length && isBlockquoteBlock(next)) {
+			run.push(next);
+			i++;
+			next = blocks[i];
+		}
+
+		if (run.length === 1) {
+			result.push(run[0]);
+		} else {
+			const group: BlockquoteGroupNode = {
+				_type: "blockquoteGroup",
+				_key: `${run[0]?._key ?? "quote"}-group`,
+				blocks: run,
+			};
+			result.push(group);
+		}
+	}
+
+	return result;
+}

package/src/content/converters/portable-text-to-prosemirror.ts

@@ -60,6 +60,37 @@ export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMir
 			}
 
 			content.push(convertList(listBlocks, listType));
+		} else if (isTextBlock(block) && block.style === "blockquote") {
+			// Collect a blockquote "run": Portable Text is flat, so a
+			// multi-paragraph quote is stored as consecutive blocks with
+			// style "blockquote" (that's what the Gutenberg importer emits
+			// and what prosemirrorToPortableText serializes back to).
+			// Without this grouping each paragraph became its own quote
+			// node, and editor merges reverted on reload (#1884).
+			const quoteBlocks: PortableTextTextBlock[] = [];
+			while (i < blocks.length) {
+				const current = blocks[i];
+				if (
+					!isTextBlock(current) ||
+					current.style !== "blockquote" ||
+					current.listItem !== undefined
+				) {
+					break;
+				}
+				quoteBlocks.push(current);
+				i++;
+			}
+
+			content.push({
+				type: "blockquote",
+				content: quoteBlocks.map((quoteBlock) => {
+					const paragraph = convertSpans(quoteBlock.children, quoteBlock.markDefs || []);
+					return {
+						type: "paragraph",
+						content: paragraph.length > 0 ? paragraph : undefined,
+					};
+				}),
+			});
 		} else {
 			const converted = convertBlock(block);
 			if (converted) {
@@ -386,7 +417,7 @@ function convertMarks(
 						// Unknown mark def type - preserve attrs
 						pmMarks.push({
 							type: markDef._type,
-							attrs: markDef as Record<string, unknown>,
+							attrs: markDef,
 						});
 					}
 				}

package/src/database/dialect-helpers.ts

@@ -68,6 +68,40 @@ export function currentTimestampValue(db: Kysely<any>): RawBuilder<string> {
 	return sql`datetime('now')`;
 }
 
+/**
+ * Build WHERE clause for status filtering on a content table.
+ * When filtering for 'published' status, also include scheduled content
+ * whose scheduled_at time has passed (treating it as effectively published).
+ *
+ * Visibility is computed, not flipped by cron, so a literal
+ * `status = 'published'` comparison undercounts scheduled-and-due entries —
+ * every "publicly visible" filter must go through this helper.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
+export function buildStatusCondition(
+	db: Kysely<any>,
+	status: string,
+	tablePrefix?: string,
+): ReturnType<typeof sql> {
+	const statusField = tablePrefix ? `${tablePrefix}.status` : "status";
+	const scheduledAtField = tablePrefix ? `${tablePrefix}.scheduled_at` : "scheduled_at";
+
+	if (status === "published") {
+		// Include both published content AND scheduled content past its publish time.
+		// scheduled_at is stored as text (ISO 8601). On Postgres, we must cast it
+		// to timestamptz for the comparison with CURRENT_TIMESTAMP to work.
+		const scheduledAtExpr = isPostgres(db)
+			? sql`${sql.ref(scheduledAtField)}::timestamptz`
+			: sql.ref(scheduledAtField);
+		const nowExpr = isPostgres(db)
+			? currentTimestampValue(db)
+			: sql`strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+		return sql`(${sql.ref(statusField)} = 'published' OR (${sql.ref(statusField)} = 'scheduled' AND ${scheduledAtExpr} <= ${nowExpr}))`;
+	}
+
+	return sql`${sql.ref(statusField)} = ${status}`;
+}
+
 /**
  * Check if a table exists in the database.
  */
@@ -181,17 +215,91 @@ export function binaryType(db: Kysely<any>): ColumnDataType {
 }
 
 /**
- * SQL expression for extracting a field from a JSON/JSONB column.
+ * SQL expression for extracting a field from a JSON column stored as text.
  *
  * sqlite:   json_extract(column, '$.path')
- * postgres: column->>'path'
+ * postgres: (column)::jsonb->>'path'
+ *
+ * The Postgres cast is required because JSON columns (e.g.
+ * `_plugin_storage.data`) are `text`, and `text ->> unknown` is not an
+ * operator. The cast is immutable, so the same expression works in
+ * expression indexes — queries and indexes must build it through this
+ * helper so the planner can match them.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
 export function jsonExtractExpr(db: Kysely<any>, column: string, path: string): string {
 	validateIdentifier(column, "JSON column name");
 	validateJsonFieldName(path, "JSON path");
 	if (isPostgres(db)) {
-		return `${column}->>'${path}'`;
+		return `(${column})::jsonb->>'${path}'`;
 	}
 	return `json_extract(${column}, '$.${path}')`;
 }
+
+/**
+ * SQL expression for extracting a queryable field from the plugin-storage
+ * `data` column.
+ *
+ * `_plugin_storage.data` is `text`, so Postgres extraction goes through the
+ * `(data)::jsonb->>'field'` cast (#1898) — otherwise `text ->> unknown` is not
+ * an operator. But the extracted value is still `text`, so a numeric comparison
+ * (`stock >= 10`) compares lexically (`'9' >= '10'` is TRUE) and silently
+ * over-counts / oversells; pass `{ numeric: true }` for a numeric comparison.
+ *
+ * The numeric form is a **type-guarded** cast, not a bare `::numeric`. A bare
+ * cast throws `invalid input syntax for type numeric` the moment a single
+ * scanned row stores a non-number in that field (documents are schemaless),
+ * aborting the whole query — and it would diverge from SQLite, which silently
+ * coerces. Guarding with `jsonb_typeof`/`json_type` makes the comparison total
+ * and parity-correct on both dialects: a non-number stored value yields `NULL`
+ * (no match) instead of an error.
+ *
+ * The field name is validated before interpolation, so the casts wrap only a
+ * safe identifier and add no injection surface.
+ *
+ * sqlite text:      json_extract(data, '$.field')
+ * sqlite numeric:   CASE WHEN json_type(data, '$.field') IN ('integer', 'real')
+ *                     THEN json_extract(data, '$.field') END
+ * postgres text:    (data)::jsonb->>'field'
+ * postgres numeric: CASE WHEN jsonb_typeof((data)::jsonb->'field') = 'number'
+ *                     THEN ((data)::jsonb->>'field')::numeric END
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
+export function pluginDataExtractExpr(
+	db: Kysely<any>,
+	field: string,
+	options?: { numeric?: boolean },
+): string {
+	validateJsonFieldName(field, "plugin storage field name");
+	if (isPostgres(db)) {
+		const text = `(data)::jsonb->>'${field}'`;
+		if (!options?.numeric) return text;
+		return `CASE WHEN jsonb_typeof((data)::jsonb->'${field}') = 'number' THEN (${text})::numeric END`;
+	}
+	const extract = `json_extract(data, '$.${field}')`;
+	if (!options?.numeric) return extract;
+	return `CASE WHEN json_type(data, '$.${field}') IN ('integer', 'real') THEN ${extract} END`;
+}
+
+/**
+ * SQL expression for ordering plugin-storage rows by a `data` field.
+ *
+ * `ORDER BY` has no bound operand to infer numeric-vs-text from, so extracting
+ * as text (`->>'field'`) would sort a numeric field lexically on Postgres
+ * (`[10, 100, 9]`) while SQLite's `json_extract` sorts it numerically — a
+ * cross-dialect divergence. Ordering over the jsonb-native value (`->'field'`,
+ * single arrow) fixes this: jsonb btree ordering is numeric among numbers,
+ * lexical among strings, and total across heterogeneous values (never throws).
+ * SQLite's `json_extract` already orders numerically, so it is unchanged.
+ *
+ * sqlite:   json_extract(data, '$.field')
+ * postgres: (data)::jsonb->'field'
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
+export function pluginDataOrderExpr(db: Kysely<any>, field: string): string {
+	validateJsonFieldName(field, "plugin storage order field name");
+	if (isPostgres(db)) {
+		return `(data)::jsonb->'${field}'`;
+	}
+	return `json_extract(data, '$.${field}')`;
+}

package/src/database/migrations/039_fix_fts5_triggers.ts

@@ -135,7 +135,7 @@ function isSearchEnabled(searchConfig: string | null): boolean {
 			typeof parsed === "object" &&
 			parsed !== null &&
 			"enabled" in parsed &&
-			(parsed as { enabled: unknown }).enabled === true
+			parsed.enabled === true
 		);
 	} catch {
 		return false;

package/src/database/migrations/051_content_taxonomies_denorm.ts

@@ -0,0 +1,120 @@
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import { columnExists, listTablesLike } from "../dialect-helpers.js";
+import { validateIdentifier } from "../validate.js";
+
+/**
+ * Denormalize the filter + sort columns from `ec_*` onto `content_taxonomies`
+ * and mirror `ec_*`'s composite sort indexes onto the pivot (#1834).
+ *
+ * A taxonomy-filtered listing used to apply the term filter as a correlated
+ * `EXISTS` on `SELECT * FROM ec_<collection> … ORDER BY … LIMIT ?`. The pivot
+ * carried only `(collection, entry_id, taxonomy_id)`, so the filter
+ * (`deleted_at`, `status`, `locale`) and the sort (`published_at`/`created_at`)
+ * could only be evaluated on the `ec_*` row. On stats-blind SQLite/D1 a
+ * selective term never fills the `LIMIT`, so the query walked the whole
+ * collection (~75k D1 rows read for a one-row page).
+ *
+ * Copying those columns onto the pivot and indexing them keyed by
+ * `(taxonomy_id, collection, …)` lets the loader seek the term and walk a
+ * sort-ordered pivot index, short-circuiting on `LIMIT`, then touch `ec_*` only
+ * by primary key to hydrate the page.
+ *
+ * The columns are advisory (D1 has no transactions; the write-path re-stamp is
+ * non-atomic), so the read path re-checks the real predicates on the joined
+ * `ec_*` row — see loader.ts. `updated_at` is deliberately not denormalized: it
+ * moves on every edit and is seldom a public sort, so its write cost outweighs
+ * its read value; `updated_at`-sorted taxonomy listings temp-sort instead.
+ *
+ * Order matters: add the columns, backfill, THEN build the indexes so each
+ * index is built once over populated data rather than maintained through the
+ * backfill `UPDATE`.
+ *
+ * Forward-only.
+ */
+
+const DENORM_COLUMNS = [
+	"status",
+	"scheduled_at",
+	"deleted_at",
+	"locale",
+	"published_at",
+	"created_at",
+] as const;
+
+// `entry_id DESC` (not ASC) matters: the listing orders `<sort> DESC, entry_id
+// DESC` (the common case), and a DESC tiebreaker lets SQLite satisfy the whole
+// ORDER BY from the index — no temp B-tree, clean early-`LIMIT`. An ASC
+// tiebreaker forces `USE TEMP B-TREE FOR LAST TERM OF ORDER BY`, which buffers
+// a whole equal-`sortval` block (e.g. a bulk import sharing one timestamp)
+// before emitting. `DESC` also serves the rarer ASC listing via a backward
+// index scan. Mirrors `ec_*`'s `(deleted_at, [locale,] <sort> DESC, id DESC)`.
+const INDEXES: { name: string; columns: string }[] = [
+	{
+		name: "idx_content_taxonomies_pub",
+		columns: "taxonomy_id, collection, deleted_at, published_at DESC, entry_id DESC",
+	},
+	{
+		name: "idx_content_taxonomies_crt",
+		columns: "taxonomy_id, collection, deleted_at, created_at DESC, entry_id DESC",
+	},
+	{
+		name: "idx_content_taxonomies_loc_pub",
+		columns: "taxonomy_id, collection, deleted_at, locale, published_at DESC, entry_id DESC",
+	},
+	{
+		name: "idx_content_taxonomies_loc_crt",
+		columns: "taxonomy_id, collection, deleted_at, locale, created_at DESC, entry_id DESC",
+	},
+];
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+	// 1. Add the six denormalized columns (all nullable, no default). Guarded so
+	//    a partial apply — or a re-run after a mid-migration failure — can retry
+	//    (`ALTER TABLE ADD COLUMN` is not itself idempotent on either dialect).
+	for (const column of DENORM_COLUMNS) {
+		if (await columnExists(db, "content_taxonomies", column)) continue;
+		await sql`
+			ALTER TABLE content_taxonomies ADD COLUMN ${sql.ref(column)} TEXT
+		`.execute(db);
+	}
+
+	// 2. Backfill from each content table by primary key. Drive from the actual
+	//    `ec_*` tables (not `_emdash_collections`) so collections whose table was
+	//    dropped are skipped naturally; the pivot's `collection` value is the
+	//    slug, i.e. the table name without its `ec_` prefix.
+	const tableNames = await listTablesLike(db, "ec_%");
+	for (const tableName of tableNames) {
+		validateIdentifier(tableName, "content table name");
+		const slug = tableName.slice("ec_".length);
+		await sql`
+			UPDATE content_taxonomies
+			SET (status, scheduled_at, deleted_at, locale, published_at, created_at) = (
+				SELECT status, scheduled_at, deleted_at, locale, published_at, created_at
+				FROM ${sql.ref(tableName)}
+				WHERE ${sql.ref(tableName)}.id = content_taxonomies.entry_id
+			)
+			WHERE collection = ${slug}
+		`.execute(db);
+	}
+
+	// 3. Build the composite sort indexes over the now-populated columns.
+	for (const index of INDEXES) {
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(index.name)}
+			ON content_taxonomies (${sql.raw(index.columns)})
+		`.execute(db);
+	}
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	for (const index of INDEXES) {
+		await sql`DROP INDEX IF EXISTS ${sql.ref(index.name)}`.execute(db);
+	}
+	for (const column of DENORM_COLUMNS) {
+		await sql`
+			ALTER TABLE content_taxonomies DROP COLUMN ${sql.ref(column)}
+		`.execute(db);
+	}
+}

package/src/database/migrations/052_media_usage_read_index.ts

@@ -0,0 +1,26 @@
+import type { Kysely } from "kysely";
+
+const OLD_INDEX = "idx__emdash_media_usage_media_id";
+const READ_INDEX = "idx__emdash_media_usage_media_source_generation";
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+	// D1 DDL is non-transactional: create the replacement before dropping the
+	// old index so an interrupted migration always leaves a media-leading index.
+	await db.schema
+		.createIndex(READ_INDEX)
+		.ifNotExists()
+		.on("_emdash_media_usage")
+		.columns(["media_id", "source_key", "generation"])
+		.execute();
+	await db.schema.dropIndex(OLD_INDEX).ifExists().execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await db.schema
+		.createIndex(OLD_INDEX)
+		.ifNotExists()
+		.on("_emdash_media_usage")
+		.column("media_id")
+		.execute();
+	await db.schema.dropIndex(READ_INDEX).ifExists().execute();
+}

package/src/database/migrations/053_plugin_mcp_tools.ts

@@ -0,0 +1,21 @@
+import type { Kysely } from "kysely";
+
+import { columnExists } from "../dialect-helpers.js";
+
+/** Persist explicit per-plugin MCP enablement and the declaration consented to by an admin. */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	if (!(await columnExists(db, "_plugin_state", "mcp_tools_enabled"))) {
+		await db.schema
+			.alterTable("_plugin_state")
+			.addColumn("mcp_tools_enabled", "integer", (col) => col.notNull().defaultTo(0))
+			.execute();
+	}
+	if (!(await columnExists(db, "_plugin_state", "mcp_tools_consent"))) {
+		await db.schema.alterTable("_plugin_state").addColumn("mcp_tools_consent", "text").execute();
+	}
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await db.schema.alterTable("_plugin_state").dropColumn("mcp_tools_consent").execute();
+	await db.schema.alterTable("_plugin_state").dropColumn("mcp_tools_enabled").execute();
+}

package/src/database/migrations/runner.ts

@@ -1,6 +1,7 @@
 import { type Kysely, sql } from "kysely";
 import { type Migration, type MigrationProvider, Migrator } from "kysely/migration";
 
+import { MIGRATION_LOCK_BUSY_MESSAGE } from "../pg-migration-lock.js";
 import type { Database } from "../types.js";
 // Import migrations statically for bundling
 import * as m001 from "./001_initial.js";
@@ -52,6 +53,9 @@ import * as m047 from "./047_restore_taxonomy_parent_index.js";
 import * as m048 from "./048_restore_content_taxonomies_term_index.js";
 import * as m049 from "./049_taxonomies_name_locale_index.js";
 import * as m050 from "./050_media_usage_index_status.js";
+import * as m051 from "./051_content_taxonomies_denorm.js";
+import * as m052 from "./052_media_usage_read_index.js";
+import * as m053 from "./053_plugin_mcp_tools.js";
 
 const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"001_initial": m001,
@@ -103,6 +107,9 @@ const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"048_restore_content_taxonomies_term_index": m048,
 	"049_taxonomies_name_locale_index": m049,
 	"050_media_usage_index_status": m050,
+	"051_content_taxonomies_denorm": m051,
+	"052_media_usage_read_index": m052,
+	"053_plugin_mcp_tools": m053,
 });
 
 /** Total number of registered migrations. Exported for use in tests. */
@@ -123,12 +130,36 @@ export interface MigrationStatus {
 	pending: string[];
 }
 
+/**
+ * Thrown when another instance held the migration lock for the whole wait
+ * window. This is NOT a migration failure — the holder may simply be slow
+ * (e.g. many pending migrations over a remote Postgres connection) — so
+ * callers with failure-backoff logic (`getDatabase` in emdash-runtime.ts)
+ * exempt it: the next request waits again instead of backing off, and init
+ * recovers as soon as the holder finishes.
+ */
+export class ConcurrentMigrationTimeoutError extends Error {
+	constructor(waitMs: number) {
+		super(
+			`Timed out waiting for another instance's migrations: the migration lock was still held after ${waitMs}ms. ` +
+				"It may still be applying migrations, or its migration may be failing repeatedly.",
+		);
+		this.name = "ConcurrentMigrationTimeoutError";
+	}
+}
+
 /** Custom migration table name */
 const MIGRATION_TABLE = "_emdash_migrations";
 const MIGRATION_LOCK_TABLE = "_emdash_migrations_lock";
 
 export interface MigrationOptions {
 	migrationTableSchema?: string;
+	/**
+	 * Override how long to wait for a concurrent migrator to finish before
+	 * giving up. Defaults to MIGRATION_RACE_WAIT_MS; tests shorten it so the
+	 * give-up path doesn't take 10 seconds per case.
+	 */
+	raceWaitMs?: number;
 }
 
 function createMigrator(db: Kysely<Database>, options?: MigrationOptions): Migrator {
@@ -260,8 +291,11 @@ async function getAppliedMigrationCount(db: Kysely<Database>): Promise<number |
  * been migrated by a newer build still treats the wait as settled instead
  * of timing out.
  */
-async function waitForConcurrentMigrator(db: Kysely<Database>): Promise<boolean> {
-	const deadline = Date.now() + MIGRATION_RACE_WAIT_MS;
+async function waitForConcurrentMigrator(
+	db: Kysely<Database>,
+	waitMs: number = MIGRATION_RACE_WAIT_MS,
+): Promise<boolean> {
+	const deadline = Date.now() + waitMs;
 	while (Date.now() < deadline) {
 		const count = await getAppliedMigrationCount(db);
 		if (count !== null && count >= MIGRATION_COUNT) {
@@ -341,13 +375,25 @@ export async function runMigrations(
 		const failedMigration = results?.find((r) => r.status === "Error");
 
 		// Concurrent-migration race: another caller is applying (or just
-		// applied) the same migration. Wait for it to finish, then verify
-		// the schema is fully migrated and treat as success.
-		if (MIGRATION_RACE_PATTERN.test(msg)) {
-			const settled = await waitForConcurrentMigrator(db);
+		// applied) the same migration. SQLite/D1 surface it as the
+		// bookkeeping UNIQUE violation (their migration lock is a no-op);
+		// Postgres surfaces it as the fail-fast advisory try-lock reporting
+		// busy (see pg-migration-lock.ts). Either way: wait for the
+		// concurrent migrator to finish, then verify the schema is fully
+		// migrated and treat as success.
+		const lockBusy = msg.includes(MIGRATION_LOCK_BUSY_MESSAGE);
+		if (MIGRATION_RACE_PATTERN.test(msg) || lockBusy) {
+			const settled = await waitForConcurrentMigrator(db, options?.raceWaitMs);
 			if (settled) {
 				return { applied };
 			}
+			if (lockBusy) {
+				// The lock holder didn't finish within the wait window —
+				// either it's slow or its migration is failing. Surface a
+				// distinct error type instead of the raw sentinel message so
+				// callers can tell "still in progress" from "failed".
+				throw new ConcurrentMigrationTimeoutError(options?.raceWaitMs ?? MIGRATION_RACE_WAIT_MS);
+			}
 		}
 
 		const failedSuffix = failedMigration ? ` (migration: ${failedMigration.migrationName})` : "";

package/src/database/pg-migration-lock.ts

@@ -0,0 +1,72 @@
+/**
+ * Fail-fast Postgres migration locking.
+ *
+ * Kysely's stock `PostgresAdapter.acquireMigrationLock` runs
+ * `select pg_advisory_xact_lock(...)` — an unbounded blocking wait on a
+ * database-wide advisory lock, held for the whole migration transaction.
+ * On Cloudflare Workers that is a stampede amplifier (#1744): every isolate
+ * that cold-starts while migrations are pending parks a connection inside
+ * Postgres waiting for the lock, and when the holder's migration fails and
+ * rolls back, the next waiter acquires the lock and re-runs the same
+ * failing migration.
+ *
+ * `FailFastPostgresDialect` swaps the blocking wait for
+ * `pg_try_advisory_xact_lock`: when another migrator holds the lock, the
+ * adapter throws `MIGRATION_LOCK_BUSY_MESSAGE` immediately instead of
+ * queueing inside the database. `runMigrations` treats that error like the
+ * SQLite/D1 concurrent-migration race — it polls the migration table with
+ * cheap bounded SELECTs until the concurrent migrator finishes (or the
+ * wait deadline passes), without holding a transaction open.
+ */
+
+import type { DialectAdapter, Kysely, MigrationLockOptions } from "kysely";
+import { PostgresAdapter as KyselyPostgresAdapter, PostgresDialect, sql } from "kysely";
+
+/**
+ * Sentinel message thrown when another migrator holds the advisory lock.
+ * `runMigrations` matches on it to route into the concurrent-migrator wait.
+ */
+export const MIGRATION_LOCK_BUSY_MESSAGE = "EMDASH_MIGRATION_LOCK_BUSY";
+
+/**
+ * Kysely's advisory lock id (LOCK_ID in kysely's postgres-adapter). Reused
+ * deliberately: during a rolling deploy, old isolates still run the stock
+ * blocking adapter, and using the same id keeps old and new builds mutually
+ * exclusive on the same lock.
+ */
+const KYSELY_PG_MIGRATION_LOCK_ID = BigInt("3853314791062309107");
+
+/**
+ * Extends the stock adapter so every capability flag and `instanceof` check
+ * is inherited, and keeps the class NAME `PostgresAdapter` because
+ * `detectDialect()` (dialect-helpers.ts) identifies the dialect via
+ * `adapter.constructor.name` — a differently-named adapter would make every
+ * dialect helper fall back to SQLite SQL against a Postgres database.
+ */
+class PostgresAdapter extends KyselyPostgresAdapter {
+	// eslint-disable-next-line typescript/no-explicit-any -- matches the DialectAdapter signature
+	override async acquireMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void> {
+		// Transaction-level lock, like the stock adapter: Postgres supports
+		// transactional DDL, so `db` here is the migration transaction and
+		// the lock is released automatically on commit/rollback.
+		const result = await sql<{ acquired: boolean }>`
+			select pg_try_advisory_xact_lock(${sql.lit(KYSELY_PG_MIGRATION_LOCK_ID)}) as acquired
+		`.execute(db);
+		if (!result.rows[0]?.acquired) {
+			throw new Error(MIGRATION_LOCK_BUSY_MESSAGE);
+		}
+	}
+}
+
+/**
+ * Drop-in replacement for Kysely's `PostgresDialect` whose migration lock
+ * fails fast instead of blocking inside the database. Everything except
+ * `createAdapter` is inherited unchanged, and because it subclasses
+ * `PostgresDialect`, the public dialect type of `emdash/db/postgres` stays
+ * `PostgresDialect` and `instanceof` checks keep working.
+ */
+export class FailFastPostgresDialect extends PostgresDialect {
+	override createAdapter(): DialectAdapter {
+		return new PostgresAdapter();
+	}
+}