emdash 0.16.1 → 0.17.1

package/src/cli/commands/export-seed.ts

@@ -9,14 +9,17 @@ import { resolve } from "node:path";
 import { defineCommand } from "citty";
 import consola from "consola";
 import type { Kysely } from "kysely";
+import { sql } from "kysely";
 
 import { createDatabase } from "../../database/connection.js";
 import { runMigrations } from "../../database/migrations/runner.js";
+import { BylineRepository } from "../../database/repositories/byline.js";
 import { ContentRepository } from "../../database/repositories/content.js";
 import { MediaRepository } from "../../database/repositories/media.js";
 import { OptionsRepository } from "../../database/repositories/options.js";
 import { TaxonomyRepository } from "../../database/repositories/taxonomy.js";
 import type { Database } from "../../database/types.js";
+import { validateIdentifier } from "../../database/validate.js";
 import { isI18nEnabled } from "../../i18n/config.js";
 import { SchemaRegistry } from "../../schema/registry.js";
 import type { FieldType } from "../../schema/types.js";
@@ -31,7 +34,10 @@ import type {
 	SeedWidgetArea,
 	SeedWidget,
 	SeedContentEntry,
+	SeedByline,
+	SeedBylineCredit,
 } from "../../seed/types.js";
+import { isMissingTableError } from "../../utils/db-errors.js";
 import { slugify } from "../../utils/slugify.js";
 
 const SETTINGS_PREFIX = "site:";
@@ -118,16 +124,29 @@ export async function exportSeed(db: Kysely<Database>, withContent?: string): Pr
 	// 2. Export collections and fields
 	seed.collections = await exportCollections(db);
 
+	// Decide locale-awareness from the data. The runtime sets the i18n config via
+	// middleware, but the CLI never does, so `isI18nEnabled()` is always false
+	// under `emdash export-seed` (#1330). Detecting multiple locales in the data
+	// keeps the export locale-aware without the runtime flag.
+	const i18nEnabled = await detectI18nEnabled(db, seed.collections);
+
 	// 3. Export taxonomy definitions and terms
-	seed.taxonomies = await exportTaxonomies(db);
+	seed.taxonomies = await exportTaxonomies(db, i18nEnabled);
 
 	// 4. Export menus
-	seed.menus = await exportMenus(db);
+	seed.menus = await exportMenus(db, i18nEnabled);
 
 	// 5. Export widget areas
 	seed.widgetAreas = await exportWidgetAreas(db);
 
-	// 6. Export content (if requested)
+	// 6. Export byline profiles. The returned map (translation_group -> seed-local
+	// id) lets content credits below reference the same ids the root list emits.
+	const { bylines, groupToSeedId } = await exportBylines(db);
+	if (bylines.length > 0) {
+		seed.bylines = bylines;
+	}
+
+	// 7. Export content (if requested)
 	if (withContent !== undefined) {
 		const collections =
 			withContent === "" || withContent === "true"
@@ -137,12 +156,112 @@ export async function exportSeed(db: Kysely<Database>, withContent?: string): Pr
 						.map((s) => s.trim())
 						.filter(Boolean);
 
-		seed.content = await exportContent(db, seed.collections || [], collections);
+		seed.content = await exportContent(
+			db,
+			seed.collections || [],
+			collections,
+			groupToSeedId,
+			i18nEnabled,
+		);
 	}
 
 	return seed;
 }
 
+/**
+ * Export byline profiles as root-level `bylines[]`.
+ *
+ * `SeedByline` has no locale axis, so locale siblings of the same byline
+ * (sharing a `translation_group`) collapse to a single profile. The returned
+ * `groupToSeedId` map keys on `translation_group` — the value stored in
+ * `_emdash_content_bylines.byline_id` — so content credits can resolve to the
+ * emitted seed id.
+ */
+async function exportBylines(
+	db: Kysely<Database>,
+): Promise<{ bylines: SeedByline[]; groupToSeedId: Map<string, string> }> {
+	const bylineRepo = new BylineRepository(db);
+	const bylines: SeedByline[] = [];
+	const groupToSeedId = new Map<string, string>();
+	const usedSeedIds = new Set<string>();
+
+	let cursor: string | undefined;
+	do {
+		const result = await bylineRepo.findMany({ limit: 100, cursor });
+		for (const byline of result.items) {
+			const group = byline.translationGroup ?? byline.id;
+			// One seed entry per translation group; first row seen wins.
+			if (groupToSeedId.has(group)) continue;
+
+			let seedId = `byline:${byline.slug}`;
+			// Disambiguate the rare case of two distinct groups sharing a slug
+			// (slug is unique per-locale, not globally) so seed ids stay unique.
+			if (usedSeedIds.has(seedId)) seedId = `byline:${byline.slug}:${group}`;
+			usedSeedIds.add(seedId);
+			groupToSeedId.set(group, seedId);
+
+			bylines.push({
+				id: seedId,
+				slug: byline.slug,
+				displayName: byline.displayName,
+				bio: byline.bio || undefined,
+				websiteUrl: byline.websiteUrl || undefined,
+				isGuest: byline.isGuest || undefined,
+			});
+		}
+		cursor = result.nextCursor;
+	} while (cursor);
+
+	return { bylines, groupToSeedId };
+}
+
+/**
+ * Determine whether the export should emit locale-suffixed seed ids.
+ *
+ * The runtime initializes the i18n config in middleware, but the CLI never does,
+ * so `isI18nEnabled()` is always false under `emdash export-seed` (#1330). When
+ * the flag is unset, fall back to the data: a project is multi-locale when its
+ * i18n-aware tables hold rows in more than one distinct locale. `locale` is
+ * NOT NULL (defaulting to the site's default locale), so a per-row presence
+ * check is not enough — only the *count* of distinct locales distinguishes a
+ * genuinely single-locale project from a multi-locale one. This keeps
+ * single-locale exports on bare ids and gives multi-locale exports the
+ * per-locale suffix they need to avoid duplicate seed ids.
+ */
+async function detectI18nEnabled(
+	db: Kysely<Database>,
+	collections: SeedCollection[],
+): Promise<boolean> {
+	if (isI18nEnabled()) return true;
+
+	const locales = new Set<string>();
+	const collectDistinctLocales = async (tableRef: ReturnType<typeof sql.ref>): Promise<boolean> => {
+		const result = await sql<{ locale: string | null }>`
+			SELECT DISTINCT locale FROM ${tableRef}
+		`.execute(db);
+		for (const row of result.rows) {
+			if (row.locale) locales.add(row.locale);
+		}
+		return locales.size > 1;
+	};
+
+	if (await collectDistinctLocales(sql.ref("_emdash_taxonomy_defs"))) return true;
+	if (await collectDistinctLocales(sql.ref("_emdash_menus"))) return true;
+
+	for (const collection of collections) {
+		validateIdentifier(collection.slug, "collection slug");
+		// On D1, deleteCollection is non-atomic, so a collection row can outlive
+		// its ec_* table. Skip missing tables rather than crashing the export.
+		try {
+			if (await collectDistinctLocales(sql.ref(`ec_${collection.slug}`))) return true;
+		} catch (error) {
+			if (!isMissingTableError(error)) throw error;
+		}
+	}
+
+	return false;
+}
+
 /**
  * Export site settings
  */
@@ -212,9 +331,10 @@ async function exportCollections(db: Kysely<Database>): Promise<SeedCollection[]
 /**
  * Export taxonomy definitions and terms
  */
-async function exportTaxonomies(db: Kysely<Database>): Promise<SeedTaxonomy[]> {
-	const i18nEnabled = isI18nEnabled();
-
+async function exportTaxonomies(
+	db: Kysely<Database>,
+	i18nEnabled: boolean,
+): Promise<SeedTaxonomy[]> {
 	// Mirrors the content export pattern: one entry per (name, locale), stable
 	// seed-local id, translations linked via `translationOf` to the anchor's id.
 	const defs = await db
@@ -306,9 +426,7 @@ async function exportTaxonomies(db: Kysely<Database>): Promise<SeedTaxonomy[]> {
 /**
  * Export menus with their items
  */
-async function exportMenus(db: Kysely<Database>): Promise<SeedMenu[]> {
-	const i18nEnabled = isI18nEnabled();
-
+async function exportMenus(db: Kysely<Database>, i18nEnabled: boolean): Promise<SeedMenu[]> {
 	const menus = await db
 		.selectFrom("_emdash_menus")
 		.selectAll()
@@ -546,6 +664,8 @@ async function exportContent(
 	db: Kysely<Database>,
 	collections: SeedCollection[],
 	includeCollections: string[] | null,
+	bylineGroupToSeedId: Map<string, string>,
+	i18nEnabled: boolean,
 ): Promise<Record<string, SeedContentEntry[]>> {
 	const content: Record<string, SeedContentEntry[]> = {};
 	const contentRepo = new ContentRepository(db);
@@ -579,8 +699,6 @@ async function exportContent(
 		// Media table might not exist or be empty
 	}
 
-	const i18nEnabled = isI18nEnabled();
-
 	for (const collection of collections) {
 		// Skip if not in include list
 		if (includeCollections && !includeCollections.includes(collection.slug)) {
@@ -642,6 +760,16 @@ async function exportContent(
 					entry.taxonomies = taxonomies;
 				}
 
+				// Get byline credits. Read the junction directly: its `byline_id`
+				// stores the translation_group, which is exactly the key in
+				// `bylineGroupToSeedId`. This is locale-agnostic (one row per
+				// credit) and avoids the locale-sibling fan-out a hydrated read
+				// would produce.
+				const bylines = await getBylineCredits(db, collection.slug, item.id, bylineGroupToSeedId);
+				if (bylines.length > 0) {
+					entry.bylines = bylines;
+				}
+
 				entries.push(entry);
 			}
 
@@ -723,6 +851,40 @@ function processDataForExport(
 	return result;
 }
 
+/**
+ * Get ordered byline credits for a content entry as `SeedBylineCredit[]`.
+ *
+ * The `_emdash_content_bylines.byline_id` column stores the credited byline's
+ * `translation_group`, so it maps straight through `groupToSeedId`. Credits
+ * whose group wasn't emitted in the root `bylines[]` are skipped (defensive;
+ * shouldn't happen for a consistent DB).
+ */
+async function getBylineCredits(
+	db: Kysely<Database>,
+	collection: string,
+	entryId: string,
+	groupToSeedId: Map<string, string>,
+): Promise<SeedBylineCredit[]> {
+	const rows = await db
+		.selectFrom("_emdash_content_bylines")
+		.select(["byline_id", "role_label"])
+		.where("collection_slug", "=", collection)
+		.where("content_id", "=", entryId)
+		.orderBy("sort_order", "asc")
+		.execute();
+
+	const credits: SeedBylineCredit[] = [];
+	for (const row of rows) {
+		const seedId = groupToSeedId.get(row.byline_id);
+		if (!seedId) continue;
+		const credit: SeedBylineCredit = { byline: seedId };
+		if (row.role_label) credit.roleLabel = row.role_label;
+		credits.push(credit);
+	}
+
+	return credits;
+}
+
 /**
  * Get taxonomy term assignments for a content entry
  */

package/src/client/index.ts

@@ -521,6 +521,7 @@ export class EmDashClient {
 			slug?: string;
 			status?: string;
 			_rev?: string;
+			locale?: string;
 		},
 	): Promise<ContentItem> {
 		// Convert markdown strings to PT
@@ -536,9 +537,11 @@ export class EmDashClient {
 			status: input.status,
 			...(input._rev ? { _rev: input._rev } : {}),
 		};
+		const params = new URLSearchParams();
+		if (input.locale) params.set("locale", input.locale);
 		const result = await this.request<{ item: ContentItem; _rev?: string }>(
 			"PUT",
-			`/content/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+			`/content/${encodeURIComponent(collection)}/${encodeURIComponent(id)}${params.toString() ? `?${params}` : ""}`,
 			body,
 		);
 

package/src/components/InlinePortableTextEditor.tsx

@@ -183,6 +183,14 @@ function convertPMNode(node: PMNode): PTBlock | PTBlock[] | null {
 				language: attrStrOpt(node.attrs, "language"),
 			};
 		}
+		case "htmlBlock": {
+			const rawHtml = node.attrs?.html;
+			return {
+				_type: "htmlBlock",
+				_key: k(),
+				html: typeof rawHtml === "string" ? rawHtml : "",
+			};
+		}
 		case "image": {
 			const provider = attrStrOpt(node.attrs, "provider");
 			return {
@@ -391,6 +399,13 @@ function convertPTBlock(block: PTBlock): JSONContent | null {
 	if (block._type === "break") {
 		return { type: "horizontalRule" };
 	}
+	if (block._type === "htmlBlock") {
+		const hb = block as PTBlock & { html?: string };
+		return {
+			type: "htmlBlock",
+			attrs: { html: hb.html || "" },
+		};
+	}
 	if (block._type === "image") {
 		const ib = block as PTBlock & {
 			asset?: { _ref?: string; url?: string; provider?: string };
@@ -731,6 +746,21 @@ const slashCommands: SlashCommandItem[] = [
 			editor.chain().focus().deleteRange(range).toggleCodeBlock().run();
 		},
 	},
+	{
+		id: "htmlBlock",
+		title: "HTML",
+		description: "Insert raw HTML",
+		icon: "< >",
+		aliases: ["html", "raw", "markup"],
+		command: ({ editor, range }) => {
+			editor
+				.chain()
+				.focus()
+				.deleteRange(range)
+				.insertContent({ type: "htmlBlock", attrs: { html: "" } })
+				.run();
+		},
+	},
 	{
 		id: "divider",
 		title: "Divider",
@@ -771,6 +801,44 @@ const initialSlashMenuState: SlashMenuState = {
 	range: null,
 };
 
+/**
+ * Minimal `htmlBlock` TipTap node for the inline (visual-editing) editor.
+ *
+ * Like PluginBlockNode below, this renders as a read-only placeholder so the
+ * block's data is preserved across edits in the visual editor. Full editing
+ * (textarea + preview) is only available in the admin editor.
+ */
+const HtmlBlockNode = Node.create({
+	name: "htmlBlock",
+	group: "block",
+	atom: true,
+	selectable: true,
+	draggable: true,
+
+	addAttributes() {
+		const noDom = { rendered: false, parseHTML: () => null };
+		return {
+			html: { default: "", ...noDom },
+		};
+	},
+
+	parseHTML() {
+		return [{ tag: 'div[data-emdash-html-block="true"]' }];
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return [
+			"div",
+			mergeAttributes(HTMLAttributes, {
+				"data-emdash-html-block": "true",
+				class: "emdash-plugin-block-placeholder",
+				contenteditable: "false",
+			}),
+			"HTML block (edit in admin)",
+		];
+	},
+});
+
 /**
  * Minimal `pluginBlock` TipTap node for the inline (visual-editing) editor.
  *
@@ -1801,6 +1869,7 @@ export function InlinePortableTextEditor({
 				mode: "all",
 			}),
 			Typography,
+			HtmlBlockNode,
 			PluginBlockNode,
 			slashCommandsExtension,
 		],

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

@@ -121,6 +121,13 @@ function convertBlock(block: PortableTextBlock): ProseMirrorNode | null {
 	if (isCodeBlock(block)) {
 		return convertCodeBlock(block);
 	}
+	if (block._type === "htmlBlock") {
+		const hb = block as PortableTextBlock & { html?: string };
+		return {
+			type: "htmlBlock",
+			attrs: { html: hb.html || "" },
+		};
+	}
 	if (block._type === "break") {
 		return { type: "horizontalRule" };
 	}

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

@@ -14,6 +14,7 @@ import type {
 	PortableTextMarkDef,
 	PortableTextImageBlock,
 	PortableTextCodeBlock,
+	PortableTextHtmlBlock,
 } from "./types.js";
 
 /**
@@ -70,6 +71,9 @@ function convertNode(node: ProseMirrorNode): PortableTextBlock | PortableTextBlo
 		case "codeBlock":
 			return convertCodeBlock(node);
 
+		case "htmlBlock":
+			return convertHtmlBlock(node);
+
 		case "image":
 			return convertImage(node);
 
@@ -268,6 +272,18 @@ function convertCodeBlock(node: ProseMirrorNode): PortableTextCodeBlock {
 	};
 }
 
+/**
+ * Convert HTML block to Portable Text
+ */
+function convertHtmlBlock(node: ProseMirrorNode): PortableTextHtmlBlock {
+	const rawHtml = node.attrs?.html;
+	return {
+		_type: "htmlBlock",
+		_key: generateKey(),
+		html: typeof rawHtml === "string" ? rawHtml : "",
+	};
+}
+
 /**
  * Convert image to Portable Text
  */

package/src/content/converters/types.ts

@@ -80,6 +80,15 @@ export interface PortableTextCodeBlock {
 	filename?: string;
 }
 
+/**
+ * HTML block (raw HTML content)
+ */
+export interface PortableTextHtmlBlock {
+	_type: "htmlBlock";
+	_key: string;
+	html: string;
+}
+
 /**
  * Unknown/custom block (preserved for plugin compatibility)
  */
@@ -96,6 +105,7 @@ export type PortableTextBlock =
 	| PortableTextTextBlock
 	| PortableTextImageBlock
 	| PortableTextCodeBlock
+	| PortableTextHtmlBlock
 	| PortableTextUnknownBlock;
 
 /**

package/src/database/migrations/041_content_locale_list_index.ts

@@ -0,0 +1,47 @@
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import { listTablesLike } from "../dialect-helpers.js";
+
+/**
+ * Migration: locale-aware composite indexes for content list queries.
+ *
+ * Addresses GitHub issue #1219. When i18n is enabled the admin content list
+ * filters by `locale` and orders by `updated_at`/`created_at`. The existing
+ * composite indexes (033/034) cover `(deleted_at, updated_at DESC, id DESC)`
+ * etc. but omit `locale`, so a locale-filtered ordered list can't be served
+ * by a single index on large tables. These indexes restore index-only paging
+ * for the locale-scoped case.
+ *
+ * Forward-only and idempotent (`IF NOT EXISTS`).
+ *
+ * Index names use a short `loc_upd`/`loc_crt` suffix rather than spelling out
+ * `deleted_locale_updated_id`: Postgres truncates identifiers to 63 bytes, and
+ * the longer form pushes the `updated`/`created` discriminator past byte 63 for
+ * slugs as short as 40 chars, making both names truncate to the same string.
+ * Keep these identical to the names in `schema/registry.ts`.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	const tableNames = await listTablesLike(db, "ec_%");
+
+	for (const tableName of tableNames) {
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(`idx_${tableName}_loc_upd`)}
+			ON ${sql.ref(tableName)} (deleted_at, locale, updated_at DESC, id DESC)
+		`.execute(db);
+
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(`idx_${tableName}_loc_crt`)}
+			ON ${sql.ref(tableName)} (deleted_at, locale, created_at DESC, id DESC)
+		`.execute(db);
+	}
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	const tableNames = await listTablesLike(db, "ec_%");
+
+	for (const tableName of tableNames) {
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${tableName}_loc_upd`)}`.execute(db);
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${tableName}_loc_crt`)}`.execute(db);
+	}
+}

package/src/database/migrations/042_byline_fields.ts

@@ -0,0 +1,157 @@
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import { currentTimestamp } from "../dialect-helpers.js";
+
+/**
+ * Byline custom fields (Discussion #1174). Adds three tables and a
+ * version-counter row in `options`. Purely additive: no change to
+ * `_emdash_bylines` columns landed by migration 040, no change to
+ * `_emdash_content_bylines`.
+ *
+ * Storage model (D11 in the design spec):
+ *
+ * - `_emdash_byline_fields` — definitions. One row per registered field.
+ * - `_emdash_byline_field_values` — translatable values, keyed by
+ *   `(byline_id, field_id)`. One value per locale variant of a byline.
+ * - `_emdash_byline_field_group_values` — non-translatable values, keyed
+ *   by `(translation_group, field_id)`. One value shared across every
+ *   locale variant of the byline's translation group.
+ *
+ * The per-field `translatable` flag (column on `_emdash_byline_fields`)
+ * decides which value table a field writes to. The split is at the
+ * storage level rather than per-row so a single SELECT … IN per locale
+ * bucket suffices for batched hydration (see Phase 3 of the PR plan).
+ *
+ * `options('byline_fields_version', '0')` is the version counter the
+ * field-definitions cache reads (Phase 3). Every mutation on
+ * `_emdash_byline_fields` bumps this row; cached defs invalidate on a
+ * mismatch. Storing it in `options` (the same table `settings/index.ts`
+ * uses) means we get the request-cache + persisted-version pattern for
+ * free — no new infrastructure.
+ *
+ * Idempotency: every `CREATE TABLE` and `CREATE INDEX` uses
+ * `.ifNotExists()`, so a partial prior run (a crash mid-migration, retried
+ * after the runner's race-recovery path or after a manual fix) re-applies
+ * cleanly — including any indexes that landed in the failed pass after the
+ * table itself. A coarse table-level guard would skip the index step if the
+ * table existed but indexes didn't (the realistic crash window between
+ * `CREATE TABLE` and the next `CREATE INDEX`). The runner records applied
+ * migrations only after a successful pass, so a crashed-then-retried `up()`
+ * is the normal recovery path here.
+ *
+ * D1 has no transactions — the schema builder and `INSERT` for the
+ * version row execute one statement at a time. Order matters: parent
+ * tables first (`_emdash_byline_fields`), then the value tables that
+ * reference it. If `down()` runs after a partial `up()`, missing tables
+ * are tolerated (`DROP TABLE IF EXISTS`).
+ */
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await db.schema
+		.createTable("_emdash_byline_fields")
+		.ifNotExists()
+		.addColumn("id", "text", (col) => col.primaryKey())
+		.addColumn("slug", "text", (col) => col.notNull().unique())
+		.addColumn("label", "text", (col) => col.notNull())
+		.addColumn("type", "text", (col) => col.notNull())
+		.addColumn("required", "integer", (col) => col.notNull().defaultTo(0))
+		.addColumn("translatable", "integer", (col) => col.notNull().defaultTo(1))
+		.addColumn("validation", "text") // JSON: { options?: string[] }
+		.addColumn("sort_order", "integer", (col) => col.notNull().defaultTo(0))
+		.addColumn("created_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.addColumn("updated_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.execute();
+
+	await db.schema
+		.createIndex("idx__emdash_byline_fields_sort_order")
+		.ifNotExists()
+		.on("_emdash_byline_fields")
+		.column("sort_order")
+		.execute();
+
+	await db.schema
+		.createTable("_emdash_byline_field_values")
+		.ifNotExists()
+		.addColumn("byline_id", "text", (col) =>
+			col.notNull().references("_emdash_bylines.id").onDelete("cascade"),
+		)
+		.addColumn("field_id", "text", (col) =>
+			col.notNull().references("_emdash_byline_fields.id").onDelete("cascade"),
+		)
+		.addColumn("value", "text") // JSON-encoded CustomFieldValue
+		.addColumn("created_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.addColumn("updated_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.addPrimaryKeyConstraint("_emdash_byline_field_values_pk", ["byline_id", "field_id"])
+		.execute();
+
+	await db.schema
+		.createIndex("idx__emdash_byline_field_values_byline")
+		.ifNotExists()
+		.on("_emdash_byline_field_values")
+		.column("byline_id")
+		.execute();
+	await db.schema
+		.createIndex("idx__emdash_byline_field_values_field")
+		.ifNotExists()
+		.on("_emdash_byline_field_values")
+		.column("field_id")
+		.execute();
+
+	await db.schema
+		.createTable("_emdash_byline_field_group_values")
+		.ifNotExists()
+		.addColumn("translation_group", "text", (col) => col.notNull())
+		.addColumn("field_id", "text", (col) =>
+			col.notNull().references("_emdash_byline_fields.id").onDelete("cascade"),
+		)
+		.addColumn("value", "text") // JSON-encoded CustomFieldValue
+		.addColumn("created_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.addColumn("updated_at", "text", (col) => col.defaultTo(currentTimestamp(db)))
+		.addPrimaryKeyConstraint("_emdash_byline_field_group_values_pk", [
+			"translation_group",
+			"field_id",
+		])
+		.execute();
+
+	await db.schema
+		.createIndex("idx__emdash_byline_field_group_values_group")
+		.ifNotExists()
+		.on("_emdash_byline_field_group_values")
+		.column("translation_group")
+		.execute();
+	await db.schema
+		.createIndex("idx__emdash_byline_field_group_values_field")
+		.ifNotExists()
+		.on("_emdash_byline_field_group_values")
+		.column("field_id")
+		.execute();
+
+	// Version-counter row read by the field-definitions cache (Phase 3).
+	// `options.value` stores JSON, so the initial counter is the JSON literal
+	// `0`. `INSERT … ON CONFLICT DO NOTHING` so a retry after a crash that
+	// landed the row but failed later in the migration does not double-insert.
+	await sql`
+		INSERT INTO options (name, value) VALUES ('byline_fields_version', '0')
+		ON CONFLICT (name) DO NOTHING
+	`.execute(db);
+}
+
+/**
+ * Reverses the schema additions and removes the version-counter row.
+ * Used by the test suite and by `rollbackMigration`; the runner itself
+ * never invokes `down()` automatically.
+ *
+ * The drops are unconditional `IF EXISTS` so a `down()` after a partial
+ * `up()` (only one or two tables landed) still settles the database back
+ * to its pre-042 state.
+ */
+export async function down(db: Kysely<unknown>): Promise<void> {
+	// Child tables first to avoid FK reference issues on Postgres. SQLite +
+	// D1 accept either order with `IF EXISTS`, but explicit ordering keeps
+	// the dialects parity-safe.
+	await db.schema.dropTable("_emdash_byline_field_group_values").ifExists().execute();
+	await db.schema.dropTable("_emdash_byline_field_values").ifExists().execute();
+	await db.schema.dropTable("_emdash_byline_fields").ifExists().execute();
+	await sql`DELETE FROM options WHERE name = 'byline_fields_version'`.execute(db);
+}