emdash 0.12.0 → 0.13.0

package/src/cli/wxr/parser.ts

@@ -75,7 +75,202 @@ export interface WxrPost {
 	tags: string[];
 	/** Custom taxonomy assignments beyond categories/tags */
 	customTaxonomies?: Map<string, string[]>;
+	/**
+	 * Display labels for per-item category/tag/custom-taxonomy assignments,
+	 * captured from `<category domain="..." nicename="...">Label</category>`
+	 * text content. Used by the importer to back-fill term labels when a
+	 * `<wp:category>` or `<wp:tag>` block wasn't present at the top of the
+	 * WXR (older / hand-edited exports). Keyed by
+	 * `${normalisedTaxonomy}\u0000${slug}` so categories and tags don't
+	 * collide.
+	 */
+	taxonomyLabels?: Map<string, string>;
 	meta: Map<string, string>;
+	/**
+	 * BCP 47 locale code extracted from a detected multilingual plugin
+	 * (WPML's `_icl_lang_code` or Polylang's per-post language taxonomy).
+	 * Absent when no per-post locale could be determined.
+	 */
+	locale?: string;
+	/**
+	 * Source-side translation group ID extracted from a detected multilingual
+	 * plugin (WPML's `trid` / `_icl_translation_id`, or a synthesized id derived
+	 * from Polylang's `_translations` meta). Posts sharing a `translationGroup`
+	 * are translations of one another. The string is opaque -- consumers use it
+	 * only as a key to link posts.
+	 */
+	translationGroup?: string;
+}
+
+/**
+ * WPML stores per-post language in postmeta as `_icl_lang_code`. The shared
+ * translation id is `trid` (this is the group ID -- every translation of the
+ * same content shares it). `_icl_translation_id` exists on some exports too
+ * but is a per-translation row id from `wp_icl_translations`, NOT the group
+ * id, so it must NOT be used as the group key. We accept it only when `trid`
+ * is absent and trust the export to be internally consistent (the only case
+ * where that's reasonable is single-post exports with no real grouping).
+ *
+ * See `wpml_element_trid` in the WPML hook docs: "the ID of the translation
+ * group".
+ */
+const WPML_LOCALE_META_KEYS = ["_icl_lang_code"] as const;
+const WPML_TRID_META_KEYS = ["trid", "_icl_translation_id"] as const;
+
+/**
+ * Polylang stores per-post language in postmeta as `_locale` on newer
+ * exports. The actual language taxonomy assignment lives on
+ * `customTaxonomies.language`, which we use as a fallback. Translation
+ * grouping is encoded in `_translations` as a serialized PHP map of
+ * `{ lang_code => post_id }`; we synthesize a stable group key from the
+ * sorted IDs so every member of the group resolves to the same string.
+ */
+const POLYLANG_LOCALE_META_KEY = "_locale";
+const POLYLANG_TRANSLATIONS_META_KEY = "_translations";
+const POLYLANG_LANG_TAXONOMY = "language";
+
+/**
+ * Extract a list of post-IDs from Polylang's `_translations` PHP-serialized
+ * value. The format we care about is roughly:
+ *
+ *   a:2:{s:2:"en";i:1;s:2:"ar";i:7;}
+ *
+ * We don't need to round-trip the PHP value -- we just need a stable group
+ * key shared by every translation of the same content. Concatenating the
+ * sorted IDs gives us exactly that: every post in the group derives the
+ * same key from its own copy of `_translations`.
+ *
+ * Naïve `/i:(\d+);/g` would also match `i:N;` literals embedded INSIDE
+ * string values (e.g. `s:11:"i:42;hello";`), which would silently corrupt
+ * the group key. We walk the serialized blob token-by-token instead.
+ *
+ * PHP serializes `s:LEN:"..."` with LEN counted in BYTES, not characters
+ * (UTF-8 byte length). JS string positions are UTF-16 code units, so we
+ * encode to bytes via `TextEncoder` and walk byte offsets. Single-byte-only
+ * inputs (the common case for Polylang's `_translations` which only stores
+ * ASCII locale codes) take the same path; the encoder is cheap.
+ */
+function polylangTranslationGroupFromMeta(serialized: string): string | undefined {
+	// Operate on the UTF-8 byte view so `s:LEN:` advances the right number
+	// of bytes when the payload contains multibyte characters.
+	const encoder = new TextEncoder();
+	const bytes = encoder.encode(serialized);
+	const decoder = new TextDecoder("utf-8");
+
+	const ids: number[] = [];
+	let i = 0;
+	const n = bytes.length;
+	const CHAR_S = 0x73; // 's'
+	const CHAR_I = 0x69; // 'i'
+	const CHAR_COLON = 0x3a; // ':'
+	const CHAR_SEMI = 0x3b; // ';'
+	const CHAR_QUOTE = 0x22; // '"'
+
+	const indexOf = (byte: number, from: number): number => {
+		for (let k = from; k < n; k++) {
+			if (bytes[k] === byte) return k;
+		}
+		return -1;
+	};
+
+	while (i < n) {
+		const ch = bytes[i];
+		if (ch === CHAR_S && bytes[i + 1] === CHAR_COLON) {
+			// s:LEN:"...";  — skip the entire string value: the LEN digits,
+			// the opening quote, the payload of exactly LEN bytes, the
+			// closing quote, and the trailing semicolon.
+			const lenStart = i + 2;
+			const lenEnd = indexOf(CHAR_COLON, lenStart);
+			if (lenEnd === -1) break;
+			const lenText = decoder.decode(bytes.slice(lenStart, lenEnd));
+			const len = Number.parseInt(lenText, 10);
+			if (!Number.isFinite(len) || len < 0) {
+				i = lenEnd + 1;
+				continue;
+			}
+			// lenEnd+1 should be `"`. Defensively check before advancing
+			// over the payload -- a malformed input shouldn't crash the
+			// import; just skip past this token.
+			if (bytes[lenEnd + 1] !== CHAR_QUOTE) {
+				i = lenEnd + 1;
+				continue;
+			}
+			const payloadStart = lenEnd + 2;
+			const afterPayload = payloadStart + len;
+			// afterPayload should point at the closing `"`; +2 past `";`.
+			i = afterPayload + 2;
+			continue;
+		}
+		if (ch === CHAR_I && bytes[i + 1] === CHAR_COLON) {
+			const valStart = i + 2;
+			const valEnd = indexOf(CHAR_SEMI, valStart);
+			if (valEnd === -1) break;
+			const idText = decoder.decode(bytes.slice(valStart, valEnd));
+			const id = Number.parseInt(idText, 10);
+			if (Number.isFinite(id)) ids.push(id);
+			i = valEnd + 1;
+			continue;
+		}
+		// Any other token (a:LEN:{...}, b:0;, N;, {, }, :, ;, etc.) -- just
+		// advance one byte. We only care about integer literals; everything
+		// else is structural.
+		i++;
+	}
+	if (ids.length === 0) return undefined;
+	const sorted = [...new Set(ids)].toSorted((a, b) => a - b);
+	return `pll:${sorted.join(",")}`;
+}
+
+/**
+ * Promote multilingual-plugin metadata from `post.meta` and
+ * `post.customTaxonomies` into `post.locale` / `post.translationGroup`.
+ *
+ * Called once per `<item>` after all of its `<wp:postmeta>` and per-item
+ * `<category>` entries have been parsed. Safe to call on posts that have no
+ * multilingual metadata -- it's a no-op in that case.
+ *
+ * WPML wins over Polylang when both are present (they shouldn't co-exist on
+ * the same site, but defensive precedence avoids ambiguity).
+ */
+function promoteI18nMetadata(post: WxrPost): void {
+	// WPML
+	for (const key of WPML_LOCALE_META_KEYS) {
+		const value = post.meta.get(key);
+		if (value) {
+			post.locale = value;
+			break;
+		}
+	}
+	for (const key of WPML_TRID_META_KEYS) {
+		const value = post.meta.get(key);
+		if (value) {
+			post.translationGroup = `wpml:${value}`;
+			break;
+		}
+	}
+
+	// Polylang fallbacks (only fill what WPML didn't already provide)
+	if (!post.locale) {
+		const pllLocale = post.meta.get(POLYLANG_LOCALE_META_KEY);
+		if (pllLocale) {
+			post.locale = pllLocale;
+		} else {
+			// Polylang's primary language signal is a taxonomy assignment
+			// on the `language` custom taxonomy. The nicename is the locale
+			// code (e.g. "en", "ar").
+			const langTaxonomy = post.customTaxonomies?.get(POLYLANG_LANG_TAXONOMY);
+			const firstLang = langTaxonomy?.[0];
+			if (firstLang) post.locale = firstLang;
+		}
+	}
+
+	if (!post.translationGroup) {
+		const pllTranslations = post.meta.get(POLYLANG_TRANSLATIONS_META_KEY);
+		if (pllTranslations) {
+			const group = polylangTranslationGroupFromMeta(pllTranslations);
+			if (group) post.translationGroup = group;
+		}
+	}
 }
 
 export interface WxrAttachment {
@@ -156,6 +351,32 @@ function attrStr(attr: string | { value: string } | undefined): string {
 	return "";
 }
 
+/**
+ * Normalise a `<category domain="...">` value to the matching EmDash
+ * taxonomy name so per-item label captures can be retrieved later using
+ * the same key.
+ */
+function normaliseDomain(domain: string): string {
+	if (domain === "post_tag") return "tag";
+	return domain;
+}
+
+/**
+ * Persist the human label of a `<category>` text body keyed by the
+ * normalised `(taxonomy, slug)` pair. Skips trivial labels that equal the
+ * slug (no information vs. just storing the slug).
+ */
+function captureItemCategoryLabel(
+	item: WxrPost,
+	pair: { domain: string; nicename: string },
+	label: string,
+): void {
+	if (!label || label === pair.nicename) return;
+	if (!item.taxonomyLabels) item.taxonomyLabels = new Map();
+	const key = `${normaliseDomain(pair.domain)}\u0000${pair.nicename}`;
+	if (!item.taxonomyLabels.has(key)) item.taxonomyLabels.set(key, label);
+}
+
 /** Type guard for complete WxrTerm (all required fields present) */
 function isCompleteWxrTerm(term: Partial<WxrTerm>): term is WxrTerm {
 	return (
@@ -194,6 +415,11 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 		let currentAuthor: WxrAuthor | null = null;
 		let currentTerm: Partial<WxrTerm> | null = null;
 		let currentMetaKey = "";
+		// Per-item category element currently open. Captured at opentag so
+		// we can pair the text body (the human label) with the slug when
+		// closetag fires. WXR per-item category elements look like:
+		//   <category domain="category" nicename="hello-world">Hello World</category>
+		let pendingItemCategory: { domain: string; nicename: string } | null = null;
 
 		// Track nav_menu_item posts for post-processing
 		const navMenuItemPosts: WxrPost[] = [];
@@ -229,8 +455,10 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 				const nicename = attrStr(node.attributes.nicename);
 				if (domain === "category" && nicename) {
 					currentItem.categories.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain === "post_tag" && nicename) {
 					currentItem.tags.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain && nicename && domain !== "category" && domain !== "post_tag") {
 					// Custom taxonomy (including nav_menu)
 					if (!currentItem.customTaxonomies) {
@@ -239,6 +467,7 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 					const existing = currentItem.customTaxonomies.get(domain) || [];
 					existing.push(nicename);
 					currentItem.customTaxonomies.set(domain, existing);
+					pendingItemCategory = { domain, nicename };
 				}
 			}
 		});
@@ -369,6 +598,18 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 							};
 						}
 						break;
+					case "category":
+						// Per-item category text body = the human label for
+						// the term (`<category nicename="hello-world">Hello
+						// World</category>`). Backfilling from per-item
+						// elements (older / hand-edited exports without top-
+						// level `<wp:category>` blocks) lands the right label
+						// instead of slug-cased nonsense.
+						if (pendingItemCategory && text) {
+							captureItemCategoryLabel(currentItem, pendingItemCategory, text);
+						}
+						pendingItemCategory = null;
+						break;
 					case "item":
 						// End of item - categorize and store
 						if (currentAttachment) {
@@ -379,6 +620,10 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 							navMenuItemPosts.push(currentItem);
 							data.posts.push(currentItem);
 						} else if (currentItem.postType !== "attachment") {
+							// Promote multilingual plugin metadata before storing.
+							// All postmeta and per-item categories are parsed by the time
+							// the closing </item> tag fires, so it's safe to inspect them.
+							promoteI18nMetadata(currentItem);
 							// Store all non-attachment post types (posts, pages, custom post types)
 							data.posts.push(currentItem);
 						}
@@ -551,6 +796,9 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 		let currentAuthor: WxrAuthor | null = null;
 		let currentTerm: Partial<WxrTerm> | null = null;
 		let currentMetaKey = "";
+		// Per-item category element currently open (see streaming-parser
+		// counterpart above for rationale).
+		let pendingItemCategory: { domain: string; nicename: string } | null = null;
 
 		// Track nav_menu_item posts for post-processing
 		const navMenuItemPosts: WxrPost[] = [];
@@ -586,8 +834,10 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 				const nicename = attrStr(node.attributes.nicename);
 				if (domain === "category" && nicename) {
 					currentItem.categories.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain === "post_tag" && nicename) {
 					currentItem.tags.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain && nicename && domain !== "category" && domain !== "post_tag") {
 					// Custom taxonomy (including nav_menu)
 					if (!currentItem.customTaxonomies) {
@@ -596,6 +846,7 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 					const existing = currentItem.customTaxonomies.get(domain) || [];
 					existing.push(nicename);
 					currentItem.customTaxonomies.set(domain, existing);
+					pendingItemCategory = { domain, nicename };
 				}
 			}
 		};
@@ -728,6 +979,14 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 							currentItem.meta.set(currentMetaKey, text);
 						}
 						break;
+					case "category":
+						// Per-item category text body = human label. See
+						// streaming-parser counterpart for rationale.
+						if (pendingItemCategory && text) {
+							captureItemCategoryLabel(currentItem, pendingItemCategory, text);
+						}
+						pendingItemCategory = null;
+						break;
 					case "item":
 						// End of item - categorize and store
 						if (currentAttachment) {
@@ -738,6 +997,10 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 							navMenuItemPosts.push(currentItem);
 							data.posts.push(currentItem);
 						} else if (currentItem.postType !== "attachment") {
+							// Promote multilingual plugin metadata before storing.
+							// All postmeta and per-item categories are parsed by the time
+							// the closing </item> tag fires, so it's safe to inspect them.
+							promoteI18nMetadata(currentItem);
 							data.posts.push(currentItem);
 						}
 						currentItem = null;

package/src/client/index.ts

@@ -737,10 +737,11 @@ export class EmDashClient {
 		if (options?.cursor) params.set("cursor", options.cursor);
 
 		const qs = params.toString();
-		return this.request<ListResult<Term>>(
+		const data = await this.request<{ terms: Term[] }>(
 			"GET",
 			`/taxonomies/${encodeURIComponent(taxonomy)}/terms${qs ? `?${qs}` : ""}`,
 		);
+		return { items: data.terms };
 	}
 
 	/** Create a taxonomy term */

package/src/database/migrations/036_i18n_menus_and_taxonomies.ts

@@ -20,18 +20,26 @@ export async function up(db: Kysely<unknown>): Promise<void> {
 	const defaultLocale = getDefaultLocale();
 
 	if (isSqlite(db)) {
-		// FKs off: rebuilding `taxonomies` would CASCADE-wipe `content_taxonomies`.
-		await sql.raw(`PRAGMA foreign_keys = OFF`).execute(db);
-		try {
-			await rebuildMenus(db, defaultLocale);
-			await addItemColumns(db, defaultLocale);
-			await rebuildTaxonomies(db, defaultLocale);
-			await rebuildTaxonomyDefs(db, defaultLocale);
-			await rebuildContentTaxonomies(db);
-			await remapMenuItemRefs(db);
-		} finally {
-			await sql.raw(`PRAGMA foreign_keys = ON`).execute(db);
-		}
+		// Rebuild children before parents to drop FKs that would CASCADE
+		// on D1. D1 enforces FKs but ignores `PRAGMA foreign_keys = OFF`
+		// (the standard SQLite escape), and its replacement
+		// `PRAGMA defer_foreign_keys = ON` only defers constraint
+		// validation, not CASCADE actions — so DROP TABLE <parent> still
+		// wipes child rows (#1021). The FKs have to be physically removed
+		// before the drop.
+		// - `content_taxonomies.taxonomy_id` → `taxonomies(id) ON DELETE CASCADE`
+		// - `_emdash_menu_items.menu_id` → `_emdash_menus(id) ON DELETE CASCADE`
+		// - `_emdash_menu_items.parent_id` → `_emdash_menu_items(id) ON DELETE CASCADE`
+		// Both FKs on `_emdash_menu_items` are stripped during the rebuild.
+		// The runtime (`MenuRepository.delete` / `setItems`) already
+		// performs the child-delete explicitly, so the loss of the cascade
+		// is invisible to callers.
+		await rebuildContentTaxonomies(db);
+		await rebuildMenuItems(db, defaultLocale);
+		await rebuildMenus(db, defaultLocale);
+		await rebuildTaxonomies(db, defaultLocale);
+		await rebuildTaxonomyDefs(db, defaultLocale);
+		await remapMenuItemRefs(db);
 		return;
 	}
 
@@ -79,17 +87,62 @@ async function rebuildMenus(db: Kysely<unknown>, defaultLocale: string): Promise
 		.execute();
 }
 
-async function addItemColumns(db: Kysely<unknown>, defaultLocale: string): Promise<void> {
+async function rebuildMenuItems(db: Kysely<unknown>, defaultLocale: string): Promise<void> {
+	// Full table rebuild rather than ALTER TABLE ADD COLUMN: this strips
+	// the `menu_id` and `parent_id` FKs from migration 005 so the
+	// subsequent `DROP TABLE _emdash_menus` can't cascade-wipe menu items
+	// on D1 (#1021). The FKs were never load-bearing at runtime — D1
+	// disables FK enforcement, and `MenuRepository` always deletes
+	// children explicitly. Mirrors `rebuildContentTaxonomies` below.
 	if (await hasColumn(db, "_emdash_menu_items", "locale")) return;
+	await sql.raw(`DROP TABLE IF EXISTS "_emdash_menu_items_new"`).execute(db);
 
 	await db.schema
-		.alterTable("_emdash_menu_items")
+		.createTable("_emdash_menu_items_new")
+		.addColumn("id", "text", (c) => c.primaryKey())
+		.addColumn("menu_id", "text", (c) => c.notNull())
+		.addColumn("parent_id", "text")
+		.addColumn("sort_order", "integer", (c) => c.notNull().defaultTo(0))
+		.addColumn("type", "text", (c) => c.notNull())
+		.addColumn("reference_collection", "text")
+		.addColumn("reference_id", "text")
+		.addColumn("custom_url", "text")
+		.addColumn("label", "text", (c) => c.notNull())
+		.addColumn("title_attr", "text")
+		.addColumn("target", "text")
+		.addColumn("css_classes", "text")
+		.addColumn("created_at", "text", (c) => c.defaultTo(currentTimestamp(db)))
 		.addColumn("locale", "text", (c) => c.notNull().defaultTo(defaultLocale))
+		.addColumn("translation_group", "text")
 		.execute();
-	await db.schema.alterTable("_emdash_menu_items").addColumn("translation_group", "text").execute();
 
-	await sql`UPDATE _emdash_menu_items SET translation_group = id`.execute(db);
+	await sql`
+		INSERT INTO _emdash_menu_items_new (
+			id, menu_id, parent_id, sort_order, type, reference_collection,
+			reference_id, custom_url, label, title_attr, target, css_classes,
+			created_at, locale, translation_group
+		)
+		SELECT
+			id, menu_id, parent_id, sort_order, type, reference_collection,
+			reference_id, custom_url, label, title_attr, target, css_classes,
+			created_at, ${defaultLocale}, id
+		FROM _emdash_menu_items
+	`.execute(db);
 
+	await db.schema.dropTable("_emdash_menu_items").execute();
+	await sql`ALTER TABLE _emdash_menu_items_new RENAME TO _emdash_menu_items`.execute(db);
+
+	// Indexes from migration 005 are dropped with the underlying table; recreate.
+	await db.schema
+		.createIndex("idx_menu_items_menu")
+		.on("_emdash_menu_items")
+		.columns(["menu_id", "sort_order"])
+		.execute();
+	await db.schema
+		.createIndex("idx_menu_items_parent")
+		.on("_emdash_menu_items")
+		.column("parent_id")
+		.execute();
 	await db.schema
 		.createIndex("idx__emdash_menu_items_locale")
 		.on("_emdash_menu_items")
@@ -118,8 +171,16 @@ async function rebuildTaxonomies(db: Kysely<unknown>, defaultLocale: string): Pr
 		.addColumn("locale", "text", (c) => c.notNull().defaultTo(defaultLocale))
 		.addColumn("translation_group", "text")
 		.addUniqueConstraint("taxonomies_name_slug_locale_unique", ["name", "slug", "locale"])
-		.addForeignKeyConstraint("taxonomies_parent_fk", ["parent_id"], "taxonomies", ["id"], (cb) =>
-			cb.onDelete("set null"),
+		// Self-FK points at `taxonomies_new` (not `taxonomies`) so dropping
+		// the old table doesn't fire ON DELETE SET NULL against parent_id
+		// values on D1. SQLite's RENAME rewrites the FK target to the new
+		// name automatically.
+		.addForeignKeyConstraint(
+			"taxonomies_parent_fk",
+			["parent_id"],
+			"taxonomies_new",
+			["id"],
+			(cb) => cb.onDelete("set null"),
 		)
 		.execute();
 
@@ -181,8 +242,13 @@ async function rebuildTaxonomyDefs(db: Kysely<unknown>, defaultLocale: string):
 }
 
 async function rebuildContentTaxonomies(db: Kysely<unknown>): Promise<void> {
-	// Drop the FK (taxonomy_id now points at translation_group, not a row id)
-	// and remap the values.
+	// Drops the FK so `taxonomy_id` can point at a translation_group rather
+	// than a row id. Runs before `rebuildTaxonomies` so the drop is safe on D1.
+	// No remap is needed here: `rebuildTaxonomies` later seeds `translation_group
+	// = id` for every preserved row, so the row-id values we copy resolve as
+	// translation_group references after the migration completes. This coupling
+	// is load-bearing — if the translation_group seed ever changes, this needs
+	// an explicit remap *after* `rebuildTaxonomies` runs.
 	const fks = await sql<{ id: number }>`PRAGMA foreign_key_list(content_taxonomies)`.execute(db);
 	if (fks.rows.length === 0) return;
 
@@ -197,15 +263,17 @@ async function rebuildContentTaxonomies(db: Kysely<unknown>): Promise<void> {
 
 	await sql`
 		INSERT OR IGNORE INTO content_taxonomies_new (collection, entry_id, taxonomy_id)
-		SELECT ct.collection, ct.entry_id, COALESCE(
-			(SELECT t.translation_group FROM taxonomies t WHERE t.id = ct.taxonomy_id),
-			ct.taxonomy_id
-		)
-		FROM content_taxonomies ct
+		SELECT collection, entry_id, taxonomy_id FROM content_taxonomies
 	`.execute(db);
 
 	await db.schema.dropTable("content_taxonomies").execute();
 	await sql`ALTER TABLE content_taxonomies_new RENAME TO content_taxonomies`.execute(db);
+
+	// SQLite drops indexes when the underlying table is dropped. Restore the
+	// taxonomy_id index from migration 015.
+	await sql`CREATE INDEX IF NOT EXISTS idx_content_taxonomies_term ON content_taxonomies(taxonomy_id)`.execute(
+		db,
+	);
 }
 
 async function remapMenuItemRefs(db: Kysely<unknown>): Promise<void> {
@@ -302,6 +370,34 @@ function validateSystemIdent(name: string): void {
 	if (!SYSTEM_IDENT.test(name)) throw new Error(`Invalid identifier: "${name}"`);
 }
 
+/**
+ * down() restores the FK on content_taxonomies. Rows whose taxonomy_id doesn't
+ * resolve to a (translation_group, defaultLocale) pair would fail the rebuild
+ * after other tables are already stripped — leaving the user mid-rollback.
+ * Surface dangling rows up front instead.
+ */
+async function assertContentTaxonomiesResolve(
+	db: Kysely<unknown>,
+	defaultLocale: string,
+): Promise<void> {
+	const result = await sql<{ count: number | string }>`
+		SELECT COUNT(*) AS count FROM content_taxonomies ct
+		WHERE NOT EXISTS (
+			SELECT 1 FROM taxonomies t
+			WHERE t.translation_group = ct.taxonomy_id AND t.locale = ${defaultLocale}
+		)
+	`.execute(db);
+	const count = Number(result.rows[0]?.count ?? 0);
+	if (count > 0) {
+		throw new Error(
+			`Cannot revert migration 036_i18n_menus_and_taxonomies: ` +
+				`${count} row(s) in "content_taxonomies" reference a translation_group ` +
+				`with no row in "taxonomies" at locale="${defaultLocale}". ` +
+				`Clean up the dangling associations before rolling back.`,
+		);
+	}
+}
+
 /**
  * down() is destructive on multi-locale installs (dropping `locale` collapses
  * translated rows onto an ambiguous unique key). Refuse to run when any row
@@ -331,6 +427,7 @@ async function assertSingleLocale(db: Kysely<unknown>, defaultLocale: string): P
 export async function down(db: Kysely<unknown>): Promise<void> {
 	const defaultLocale = getDefaultLocale();
 	await assertSingleLocale(db, defaultLocale);
+	await assertContentTaxonomiesResolve(db, defaultLocale);
 
 	const widenedTables = [
 		"_emdash_menus",
@@ -340,23 +437,28 @@ export async function down(db: Kysely<unknown>): Promise<void> {
 	];
 
 	if (isSqlite(db)) {
-		// FKs off — same reason as up().
-		await sql.raw(`PRAGMA foreign_keys = OFF`).execute(db);
-		try {
-			// Indexes first: a locale index blocks DROP COLUMN on _emdash_menu_items.
-			for (const t of widenedTables) {
-				await sql.raw(`DROP INDEX IF EXISTS idx_${t}_locale`).execute(db);
-				await sql.raw(`DROP INDEX IF EXISTS idx_${t}_translation_group`).execute(db);
-			}
-
-			await rebuildContentTaxonomiesDown(db, defaultLocale);
-			await rebuildMenusDown(db);
-			await rebuildMenuItemsDown(db);
-			await rebuildTaxonomiesDown(db);
-			await rebuildTaxonomyDefsDown(db);
-		} finally {
-			await sql.raw(`PRAGMA foreign_keys = ON`).execute(db);
+		// Indexes first: the locale index on _emdash_menu_items would
+		// otherwise block its DROP COLUMN.
+		for (const t of widenedTables) {
+			await sql.raw(`DROP INDEX IF EXISTS idx_${t}_locale`).execute(db);
+			await sql.raw(`DROP INDEX IF EXISTS idx_${t}_translation_group`).execute(db);
 		}
+
+		// Remap content_taxonomies values back to row ids while `taxonomies`
+		// still has `translation_group` + `locale`. No FK is restored yet, so
+		// the subsequent DROP TABLE taxonomies can't cascade on D1 (#1021).
+		await remapContentTaxonomiesDown(db, defaultLocale);
+		// Menus first: safe because up() stripped the cascade FK from
+		// _emdash_menu_items.menu_id, so dropping _emdash_menus doesn't
+		// cascade. The FK from migration 005 is NOT restored on
+		// _emdash_menu_items: the runtime deletes children explicitly,
+		// so the only observable effect of the FK was the #1021 cascade
+		// we're trying to avoid.
+		await rebuildMenusDown(db);
+		await rebuildMenuItemsDown(db);
+		await rebuildTaxonomiesDown(db);
+		await rebuildTaxonomyDefsDown(db);
+		await restoreContentTaxonomiesFk(db);
 		return;
 	}
 
@@ -368,10 +470,24 @@ export async function down(db: Kysely<unknown>): Promise<void> {
 	}
 }
 
-async function rebuildContentTaxonomiesDown(
+async function remapContentTaxonomiesDown(
 	db: Kysely<unknown>,
 	defaultLocale: string,
 ): Promise<void> {
+	// Map translation_group back to row id (assertSingleLocale guarantees 1:1)
+	// without restoring the FK — that happens after `taxonomies` is rebuilt.
+	await sql`
+		UPDATE content_taxonomies
+		SET taxonomy_id = COALESCE(
+			(SELECT t.id FROM taxonomies t
+			 WHERE t.translation_group = content_taxonomies.taxonomy_id
+				 AND t.locale = ${defaultLocale}),
+			taxonomy_id
+		)
+	`.execute(db);
+}
+
+async function restoreContentTaxonomiesFk(db: Kysely<unknown>): Promise<void> {
 	await sql.raw(`DROP TABLE IF EXISTS "content_taxonomies_new"`).execute(db);
 	await db.schema
 		.createTable("content_taxonomies_new")
@@ -388,18 +504,17 @@ async function rebuildContentTaxonomiesDown(
 		)
 		.execute();
 
-	// Map translation_group back to a row id (assertSingleLocale guarantees a 1:1 match).
 	await sql`
 		INSERT OR IGNORE INTO content_taxonomies_new (collection, entry_id, taxonomy_id)
-		SELECT ct.collection, ct.entry_id, COALESCE(
-			(SELECT t.id FROM taxonomies t WHERE t.translation_group = ct.taxonomy_id AND t.locale = ${defaultLocale}),
-			ct.taxonomy_id
-		)
-		FROM content_taxonomies ct
+		SELECT collection, entry_id, taxonomy_id FROM content_taxonomies
 	`.execute(db);
 
 	await db.schema.dropTable("content_taxonomies").execute();
 	await sql`ALTER TABLE content_taxonomies_new RENAME TO content_taxonomies`.execute(db);
+
+	await sql`CREATE INDEX IF NOT EXISTS idx_content_taxonomies_term ON content_taxonomies(taxonomy_id)`.execute(
+		db,
+	);
 }
 
 async function rebuildMenusDown(db: Kysely<unknown>): Promise<void> {
@@ -421,7 +536,9 @@ async function rebuildMenusDown(db: Kysely<unknown>): Promise<void> {
 }
 
 async function rebuildMenuItemsDown(db: Kysely<unknown>): Promise<void> {
-	// No UNIQUE on (locale,…) here, so DROP COLUMN is enough.
+	// No UNIQUE on (locale,…) here, so DROP COLUMN suffices. The migration-005
+	// FKs are NOT restored: up() removed them to fix #1021, and the runtime
+	// already deletes child rows explicitly so the cascade isn't needed.
 	await sql.raw(`ALTER TABLE _emdash_menu_items DROP COLUMN locale`).execute(db);
 	await sql.raw(`ALTER TABLE _emdash_menu_items DROP COLUMN translation_group`).execute(db);
 }