@growth-labs/cms 0.1.0

package/src/engine/publisher.ts

@@ -0,0 +1,1032 @@
+// The publishing engine — the content data-access CORE.
+//
+// Ported verbatim from fulcrum-labs/fronts src/lib/publisher.ts (inventory
+// §1 + §6: extract). The engine takes an injected D1Database (the site
+// supplies its own binding); NO Fronts imports remain:
+//   - the Fronts `D1Database` ambient type → package-local `./d1` (structural).
+//   - the Fronts `./primary-categories` `PrimaryCategorySlug` theme-token →
+//     `string | null` (site-supplied taxonomy). The `'analysis'` default is
+//     preserved verbatim as the documented Fronts default; a site can pass any
+//     value.
+//   - `initialVideoProcessingState` from `./foundry/video-processing`
+//     (bead 08) is inlined here as a constant; the bead-08 media glue remains
+//     the source of truth for the rest of the video state machine.
+//
+// CRITICAL (inventory §6): `duplicateContentItem` does FOUR `INSERT … SELECT`
+// copies whose explicit column lists are hand-maintained and must stay
+// positionally aligned to the live schema. `created_at`/`updated_at` are
+// deliberately OMITTED so the copy gets fresh `DEFAULT (unixepoch())`
+// timestamps; the video copy hard-codes `processing_state = 'ready'` so a
+// duplicate is NOT re-queued to Foundry. Any future `content_items` column
+// addition requires a matching edit here or the duplicate silently drops it.
+import type { D1Database } from './d1.js'
+import { evaluateArticleBody, type PublishGuardOutcome } from './publish-guard.js'
+import { slugify } from './slug.js'
+
+type ContentType = 'article' | 'video' | 'podcast' | 'newsletter'
+type ContentVisibility = 'free' | 'premium'
+
+/**
+ * The processing_state a freshly created video starts in. Mirrors
+ * fulcrum-labs/fronts `foundry/video-processing.ts` `initialVideoProcessingState`
+ * (bead 08 owns the full state machine). Inlined here so the data-access core
+ * carries no media-glue dependency.
+ */
+const initialVideoProcessingState = 'pending'
+
+const WORDS_PER_MINUTE = 200
+
+export class PublishContentValidationError extends Error {
+	readonly errors: PublishGuardOutcome['errors']
+	readonly summary: string
+
+	constructor(outcome: PublishGuardOutcome) {
+		super('Article body failed pre-publish validation')
+		this.name = 'PublishContentValidationError'
+		this.errors = outcome.errors
+		this.summary = outcome.summary
+	}
+}
+
+/** Strip markdown syntax and count words */
+export function countWords(text: string): number {
+	const plain = text
+		.replace(/```[\s\S]*?```/g, '') // code blocks
+		.replace(/`[^`]+`/g, '') // inline code
+		.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // links/images
+		.replace(/[#*_~>|`-]/g, '') // markdown syntax chars
+		.trim()
+	if (!plain) return 0
+	return plain.split(/\s+/).filter(Boolean).length
+}
+
+/** Estimate reading time in minutes (minimum 1) */
+export function estimateReadTime(wordCount: number): number {
+	return Math.max(1, Math.round(wordCount / WORDS_PER_MINUTE))
+}
+
+export interface BaseContentInput {
+	slug: string
+	title: string
+	seoTitle?: string | null
+	description?: string | null
+	excerpt?: string | null
+	byline?: string | null
+	/**
+	 * Theme-token taxonomy (site-supplied vocabulary). Stored in
+	 * `content_items.channel`. Defaults to `'analysis'` (the Fronts default)
+	 * when omitted on create.
+	 */
+	primaryCategory?: string | null
+	primaryTopic?: string | null
+	featured?: boolean
+	visibility?: ContentVisibility
+	authorId?: string | null
+	heroImageId?: string | null
+	heroImageAlt?: string | null
+	heroImageCaption?: string | null
+	socialImageId?: string | null
+	canonicalUrl?: string | null
+	tags?: string[]
+	/** The SEO focus keyword for this content item (migration 0004 column). */
+	seoFocusKeyword?: string | null
+}
+
+export interface ArticleInput extends BaseContentInput {
+	type: 'article'
+	content: {
+		bodyMarkdown: string
+		bodyHtml?: string | null
+		subtitle?: string | null
+		wordCount?: number | null
+		readTimeMinutes?: number | null
+		editorTakeaways?: string[] | null
+	}
+}
+
+export interface VideoInput extends BaseContentInput {
+	type: 'video'
+	content: {
+		script: string
+		videoId: string
+		durationSeconds?: number | null
+		thumbnailImageId?: string | null
+		processingSourceUrl?: string | null
+		processingSourceKind?: string | null
+	}
+}
+
+export interface PodcastInput extends BaseContentInput {
+	type: 'podcast'
+	content: {
+		transcript: string
+		audioR2Key: string
+		durationSeconds?: number | null
+	}
+}
+
+export interface NewsletterInput extends BaseContentInput {
+	type: 'newsletter'
+	content: {
+		bodyMarkdown: string
+		bodyHtml?: string | null
+		subtitle?: string | null
+		wordCount?: number | null
+		readTimeMinutes?: number | null
+		editorTakeaways?: string[] | null
+	}
+}
+
+export type CreateContentInput = ArticleInput | VideoInput | PodcastInput | NewsletterInput
+
+export interface UpdateContentInput extends Partial<BaseContentInput> {
+	content?: Partial<ArticleInput['content'] | VideoInput['content'] | PodcastInput['content']>
+	relations?: Array<{
+		relatedId: string
+		rank: number
+		reason?: string | null
+	}>
+	aiLockedFields?: string[]
+}
+
+/**
+ * The shape `getContentItem` returns from `SELECT * FROM content_items`.
+ * Note this is the engine's read-side row (nullable `featured`/timestamps as
+ * D1 returns them); the strict migration-contract row type lives in
+ * `@growth-labs/cms` schema as `ContentItemRow`.
+ */
+export interface ContentItemRecord {
+	id: string
+	type: ContentType
+	status: string
+	visibility: ContentVisibility
+	slug: string
+	title: string
+	seo_title: string | null
+	description: string | null
+	excerpt: string | null
+	byline: string | null
+	channel: string | null
+	primary_topic: string | null
+	featured: number | null
+	author_id: string | null
+	hero_image_id: string | null
+	hero_image_alt: string | null
+	hero_image_caption: string | null
+	social_image_id: string | null
+	canonical_url: string | null
+	publish_at: number | null
+	published_at: number | null
+	publish_tz: string | null
+	ai_locked_fields: string | null
+	published_revision_id: string | null
+	seo_focus_keyword: string | null
+	created_at: number | null
+	updated_at: number | null
+}
+
+export async function ensureUniqueSlug(
+	db: D1Database,
+	slug: string,
+	excludeId?: string,
+): Promise<string> {
+	const base = slugify(slug)
+	let candidate = base
+	let suffix = 2
+
+	while (true) {
+		const row = await db
+			.prepare('SELECT id FROM content_items WHERE slug = ? LIMIT 1')
+			.bind(candidate)
+			.first<{ id: string }>()
+
+		if (!row || (excludeId && row.id === excludeId)) {
+			return candidate
+		}
+
+		candidate = `${base}-${suffix}`
+		suffix += 1
+	}
+}
+
+function normalizeTags(tags?: string[]): string[] {
+	if (!tags) return []
+	return tags
+		.map((tag) => slugify(tag))
+		.filter(Boolean)
+		.slice(0, 10)
+}
+
+function serializeTakeaways(value: string[] | null | undefined): string | null {
+	if (!value) return null
+	const normalized = value
+		.map((item) => item.trim())
+		.filter(Boolean)
+		.slice(0, 4)
+	return normalized.length > 0 ? JSON.stringify(normalized) : null
+}
+
+async function ensureTags(db: D1Database, tags: string[]): Promise<{ id: string; slug: string }[]> {
+	const normalized = normalizeTags(tags)
+	const results: { id: string; slug: string }[] = []
+
+	for (const tag of normalized) {
+		const existing = await db
+			.prepare('SELECT id, slug FROM content_tags WHERE slug = ? LIMIT 1')
+			.bind(tag)
+			.first<{ id: string; slug: string }>()
+
+		if (existing) {
+			results.push(existing)
+			continue
+		}
+
+		const id = crypto.randomUUID()
+		await db
+			.prepare('INSERT INTO content_tags (id, slug, label) VALUES (?, ?, ?)')
+			.bind(id, tag, tag)
+			.run()
+
+		results.push({ id, slug: tag })
+	}
+
+	return results
+}
+
+export async function setContentTags(
+	db: D1Database,
+	contentId: string,
+	tags: string[],
+): Promise<void> {
+	const normalized = normalizeTags(tags)
+	await db.prepare('DELETE FROM content_tag_links WHERE content_id = ?').bind(contentId).run()
+	if (normalized.length === 0) return
+
+	const tagRows = await ensureTags(db, normalized)
+
+	const insert = db.prepare('INSERT INTO content_tag_links (content_id, tag_id) VALUES (?, ?)')
+
+	for (const tag of tagRows) {
+		await insert.bind(contentId, tag.id).run()
+	}
+}
+
+export async function setContentRelations(
+	db: D1Database,
+	contentId: string,
+	relations: Array<{ relatedId: string; rank: number; reason?: string | null }>,
+): Promise<void> {
+	await db.prepare('DELETE FROM content_relations WHERE content_id = ?').bind(contentId).run()
+	if (relations.length === 0) return
+
+	const insert = db.prepare(
+		'INSERT INTO content_relations (content_id, related_id, rank, reason) VALUES (?, ?, ?, ?)',
+	)
+
+	for (const rel of relations) {
+		await insert.bind(contentId, rel.relatedId, rel.rank, rel.reason || null).run()
+	}
+}
+
+export async function getContentRelations(
+	db: D1Database,
+	contentId: string,
+): Promise<Array<{ related_id: string; rank: number; reason: string | null }>> {
+	const result = await db
+		.prepare(
+			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC',
+		)
+		.bind(contentId)
+		.all<{ related_id: string; rank: number; reason: string | null }>()
+	return result.results || []
+}
+
+export async function createContent(
+	db: D1Database,
+	input: CreateContentInput,
+): Promise<{ id: string; slug: string }> {
+	const id = crypto.randomUUID()
+	const slug = await ensureUniqueSlug(db, input.slug)
+	const visibility = input.visibility || 'free'
+	const primaryCategory = input.primaryCategory || 'analysis'
+
+	await db
+		.prepare(
+			`
+      INSERT INTO content_items (
+        id, type, status, visibility, slug, title, seo_title, description, excerpt,
+        byline, channel, primary_topic, featured, author_id, hero_image_id,
+        hero_image_alt, hero_image_caption, social_image_id, canonical_url
+      ) VALUES (?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `,
+		)
+		.bind(
+			id,
+			input.type,
+			visibility,
+			slug,
+			input.title,
+			input.seoTitle || null,
+			input.description || null,
+			input.excerpt || null,
+			input.byline || null,
+			primaryCategory,
+			input.primaryTopic || null,
+			input.featured ? 1 : 0,
+			input.authorId || null,
+			input.heroImageId || null,
+			input.heroImageAlt || null,
+			input.heroImageCaption || null,
+			input.socialImageId || null,
+			input.canonicalUrl || null,
+		)
+		.run()
+
+	if (input.type === 'article' || input.type === 'newsletter') {
+		const wc = input.content.wordCount ?? countWords(input.content.bodyMarkdown)
+		const rt = input.content.readTimeMinutes ?? estimateReadTime(wc)
+		await db
+			.prepare(
+				`INSERT INTO article_content (content_id, body_markdown, body_html, word_count, read_time_minutes, subtitle, editor_takeaways)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			)
+			.bind(
+				id,
+				input.content.bodyMarkdown,
+				input.content.bodyHtml || null,
+				wc || null,
+				rt || null,
+				input.content.subtitle || null,
+				serializeTakeaways(input.content.editorTakeaways),
+			)
+			.run()
+	}
+
+	if (input.type === 'video') {
+		await db
+			.prepare(
+				`INSERT INTO video_content (
+					content_id,
+					script,
+					video_id,
+					duration_seconds,
+					thumbnail_image_id,
+					processing_state,
+					processing_source_url,
+					processing_source_kind
+				) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+			)
+			.bind(
+				id,
+				input.content.script,
+				input.content.videoId,
+				input.content.durationSeconds || null,
+				input.content.thumbnailImageId || null,
+				initialVideoProcessingState,
+				input.content.processingSourceUrl || null,
+				input.content.processingSourceKind || null,
+			)
+			.run()
+	}
+
+	if (input.type === 'podcast') {
+		await db
+			.prepare(
+				`INSERT INTO podcast_content (content_id, transcript, audio_r2_key, duration_seconds)
+         VALUES (?, ?, ?, ?)`,
+			)
+			.bind(
+				id,
+				input.content.transcript,
+				input.content.audioR2Key,
+				input.content.durationSeconds || null,
+			)
+			.run()
+	}
+
+	if (input.tags) {
+		await setContentTags(db, id, input.tags)
+	}
+
+	return { id, slug }
+}
+
+export async function getContentItem(
+	db: D1Database,
+	id: string,
+): Promise<ContentItemRecord | null> {
+	return db
+		.prepare('SELECT * FROM content_items WHERE id = ? LIMIT 1')
+		.bind(id)
+		.first<ContentItemRecord>()
+}
+
+export async function updateContentItem(
+	db: D1Database,
+	id: string,
+	input: UpdateContentInput,
+): Promise<{ slug: string } | null> {
+	const existing = await getContentItem(db, id)
+	if (!existing) return null
+
+	const hasOwn = (source: object, key: string) => Object.hasOwn(source, key)
+
+	const slug = input.slug ? await ensureUniqueSlug(db, input.slug, id) : existing.slug
+	const visibility = input.visibility || existing.visibility
+	const featured =
+		typeof input.featured === 'boolean' ? (input.featured ? 1 : 0) : existing.featured || 0
+	const primaryCategory = hasOwn(input, 'primaryCategory')
+		? (input.primaryCategory ?? null)
+		: (existing.channel ?? 'analysis')
+	const aiLockedFields =
+		input.aiLockedFields !== undefined
+			? JSON.stringify(input.aiLockedFields)
+			: existing.ai_locked_fields || '[]'
+	const title = hasOwn(input, 'title') ? (input.title ?? existing.title) : existing.title
+	const seoTitle = hasOwn(input, 'seoTitle') ? (input.seoTitle ?? null) : existing.seo_title
+	const description = hasOwn(input, 'description')
+		? (input.description ?? null)
+		: existing.description
+	const excerpt = hasOwn(input, 'excerpt') ? (input.excerpt ?? null) : existing.excerpt
+	const byline = hasOwn(input, 'byline') ? (input.byline ?? null) : existing.byline
+	const primaryTopic = hasOwn(input, 'primaryTopic')
+		? (input.primaryTopic ?? null)
+		: existing.primary_topic
+	const authorId = hasOwn(input, 'authorId') ? (input.authorId ?? null) : existing.author_id
+	const heroImageId = hasOwn(input, 'heroImageId')
+		? (input.heroImageId ?? null)
+		: existing.hero_image_id
+	const heroImageAlt = hasOwn(input, 'heroImageAlt')
+		? (input.heroImageAlt ?? null)
+		: existing.hero_image_alt
+	const heroImageCaption = hasOwn(input, 'heroImageCaption')
+		? (input.heroImageCaption ?? null)
+		: existing.hero_image_caption
+	const socialImageId = hasOwn(input, 'socialImageId')
+		? (input.socialImageId ?? null)
+		: existing.social_image_id
+	const canonicalUrl = hasOwn(input, 'canonicalUrl')
+		? (input.canonicalUrl ?? null)
+		: existing.canonical_url
+	const seoFocusKeyword = hasOwn(input, 'seoFocusKeyword')
+		? (input.seoFocusKeyword ?? null)
+		: (existing.seo_focus_keyword ?? null)
+
+	await db
+		.prepare(
+			`
+      UPDATE content_items SET
+        slug = ?,
+        title = ?,
+        seo_title = ?,
+        description = ?,
+        excerpt = ?,
+        byline = ?,
+        channel = ?,
+        primary_topic = ?,
+        featured = ?,
+        visibility = ?,
+        author_id = ?,
+        hero_image_id = ?,
+        hero_image_alt = ?,
+        hero_image_caption = ?,
+        social_image_id = ?,
+        canonical_url = ?,
+        ai_locked_fields = ?,
+        seo_focus_keyword = ?,
+        updated_at = unixepoch()
+      WHERE id = ?
+      `,
+		)
+		.bind(
+			slug,
+			title,
+			seoTitle,
+			description,
+			excerpt,
+			byline,
+			primaryCategory,
+			primaryTopic,
+			featured,
+			visibility,
+			authorId,
+			heroImageId,
+			heroImageAlt,
+			heroImageCaption,
+			socialImageId,
+			canonicalUrl,
+			aiLockedFields,
+			seoFocusKeyword,
+			id,
+		)
+		.run()
+
+	if (input.tags !== undefined) {
+		await setContentTags(db, id, input.tags)
+	}
+
+	if (input.relations !== undefined) {
+		await setContentRelations(db, id, input.relations)
+	}
+
+	if (input.content) {
+		if (existing.type === 'article' || existing.type === 'newsletter') {
+			const current = await db
+				.prepare(
+					`
+          SELECT body_markdown, body_html, word_count, read_time_minutes, subtitle, editor_takeaways
+          FROM article_content
+          WHERE content_id = ?
+          LIMIT 1
+          `,
+				)
+				.bind(id)
+				.first<{
+					body_markdown: string
+					body_html: string | null
+					word_count: number | null
+					read_time_minutes: number | null
+					subtitle: string | null
+					editor_takeaways: string | null
+				}>()
+			if (!current) return { slug }
+
+			const articleContent = input.content as Partial<ArticleInput['content']>
+			const bodyMarkdownProvided = hasOwn(articleContent, 'bodyMarkdown')
+			const wordCountProvided = hasOwn(articleContent, 'wordCount')
+			const readTimeProvided = hasOwn(articleContent, 'readTimeMinutes')
+			const nextBodyMarkdown = bodyMarkdownProvided
+				? (articleContent.bodyMarkdown ?? current.body_markdown)
+				: current.body_markdown
+			const nextWordCount = wordCountProvided
+				? (articleContent.wordCount ?? null)
+				: bodyMarkdownProvided
+					? nextBodyMarkdown
+						? countWords(nextBodyMarkdown)
+						: null
+					: current.word_count
+			const nextReadTime = readTimeProvided
+				? (articleContent.readTimeMinutes ?? null)
+				: bodyMarkdownProvided
+					? nextWordCount
+						? estimateReadTime(nextWordCount)
+						: null
+					: current.read_time_minutes
+			await db
+				.prepare(
+					`
+          UPDATE article_content SET
+            body_markdown = ?,
+            body_html = ?,
+            word_count = ?,
+            read_time_minutes = ?,
+            subtitle = ?,
+            editor_takeaways = ?,
+            ai_takeaways_at = CASE WHEN ? THEN NULL ELSE ai_takeaways_at END
+          WHERE content_id = ?
+          `,
+				)
+				.bind(
+					nextBodyMarkdown,
+					hasOwn(articleContent, 'bodyHtml')
+						? (articleContent.bodyHtml ?? null)
+						: bodyMarkdownProvided
+							? null
+							: current.body_html,
+					nextWordCount,
+					nextReadTime,
+					hasOwn(articleContent, 'subtitle') ? (articleContent.subtitle ?? null) : current.subtitle,
+					hasOwn(articleContent, 'editorTakeaways')
+						? serializeTakeaways(articleContent.editorTakeaways)
+						: current.editor_takeaways,
+					existing.status === 'published' && bodyMarkdownProvided ? 1 : 0,
+					id,
+				)
+				.run()
+		}
+
+		if (existing.type === 'video') {
+			const current = await db
+				.prepare(
+					`
+          SELECT script, video_id, duration_seconds, thumbnail_image_id,
+            processing_source_url, processing_source_kind
+          FROM video_content
+          WHERE content_id = ?
+          LIMIT 1
+          `,
+				)
+				.bind(id)
+				.first<{
+					script: string
+					video_id: string
+					duration_seconds: number | null
+					thumbnail_image_id: string | null
+					processing_source_url: string | null
+					processing_source_kind: string | null
+				}>()
+			if (!current) return { slug }
+
+			const videoContent = input.content as Partial<VideoInput['content']>
+			const nextSourceUrl = hasOwn(videoContent, 'processingSourceUrl')
+				? (videoContent.processingSourceUrl ?? null)
+				: current.processing_source_url
+			const nextSourceKind = hasOwn(videoContent, 'processingSourceKind')
+				? (videoContent.processingSourceKind ?? null)
+				: current.processing_source_kind
+			const sourceChanged =
+				nextSourceUrl !== current.processing_source_url ||
+				nextSourceKind !== current.processing_source_kind
+			await db
+				.prepare(
+					`
+          UPDATE video_content SET
+            script = ?,
+            video_id = ?,
+            duration_seconds = ?,
+            thumbnail_image_id = ?,
+            processing_source_url = ?,
+            processing_source_kind = ?,
+            processing_state = CASE WHEN ? THEN 'pending' ELSE processing_state END,
+            processing_correlation_id = CASE WHEN ? THEN NULL ELSE processing_correlation_id END,
+            processing_trigger_token = CASE WHEN ? THEN NULL ELSE processing_trigger_token END,
+            processing_started_at = CASE WHEN ? THEN NULL ELSE processing_started_at END,
+            processing_completed_at = CASE WHEN ? THEN NULL ELSE processing_completed_at END,
+            processing_last_event_at = CASE WHEN ? THEN NULL ELSE processing_last_event_at END,
+            processing_error = CASE WHEN ? THEN NULL ELSE processing_error END,
+            source_fetched = CASE WHEN ? THEN 0 ELSE source_fetched END,
+            transcript_ready = CASE WHEN ? THEN 0 ELSE transcript_ready END,
+            hls_ready = CASE WHEN ? THEN 0 ELSE hls_ready END,
+            transcript_url = CASE WHEN ? THEN NULL ELSE transcript_url END,
+            hls_manifest_url = CASE WHEN ? THEN NULL ELSE hls_manifest_url END,
+            hls_poster_url = CASE WHEN ? THEN NULL ELSE hls_poster_url END
+          WHERE content_id = ?
+          `,
+				)
+				.bind(
+					hasOwn(videoContent, 'script') ? (videoContent.script ?? current.script) : current.script,
+					hasOwn(videoContent, 'videoId')
+						? (videoContent.videoId ?? current.video_id)
+						: current.video_id,
+					hasOwn(videoContent, 'durationSeconds')
+						? (videoContent.durationSeconds ?? null)
+						: current.duration_seconds,
+					hasOwn(videoContent, 'thumbnailImageId')
+						? (videoContent.thumbnailImageId ?? null)
+						: current.thumbnail_image_id,
+					nextSourceUrl,
+					nextSourceKind,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					sourceChanged ? 1 : 0,
+					id,
+				)
+				.run()
+		}
+
+		if (existing.type === 'podcast') {
+			const current = await db
+				.prepare(
+					`
+          SELECT transcript, audio_r2_key, duration_seconds
+          FROM podcast_content
+          WHERE content_id = ?
+          LIMIT 1
+          `,
+				)
+				.bind(id)
+				.first<{
+					transcript: string
+					audio_r2_key: string
+					duration_seconds: number | null
+				}>()
+			if (!current) return { slug }
+
+			const podcastContent = input.content as Partial<PodcastInput['content']>
+			await db
+				.prepare(
+					`
+          UPDATE podcast_content SET
+            transcript = ?,
+            audio_r2_key = ?,
+            duration_seconds = ?
+          WHERE content_id = ?
+          `,
+				)
+				.bind(
+					hasOwn(podcastContent, 'transcript')
+						? (podcastContent.transcript ?? current.transcript)
+						: current.transcript,
+					hasOwn(podcastContent, 'audioR2Key')
+						? (podcastContent.audioR2Key ?? current.audio_r2_key)
+						: current.audio_r2_key,
+					hasOwn(podcastContent, 'durationSeconds')
+						? (podcastContent.durationSeconds ?? null)
+						: current.duration_seconds,
+					id,
+				)
+				.run()
+		}
+	}
+
+	return { slug }
+}
+
+export async function scheduleContent(
+	db: D1Database,
+	id: string,
+	publishAt: number,
+	publishTz = 'Europe/Paris',
+): Promise<void> {
+	await db
+		.prepare(
+			`UPDATE content_items SET status = 'scheduled', publish_at = ?, publish_tz = ?, updated_at = unixepoch() WHERE id = ?`,
+		)
+		.bind(publishAt, publishTz, id)
+		.run()
+}
+
+export async function evaluateContentBodyForPublish(
+	db: D1Database,
+	id: string,
+	source: string,
+): Promise<PublishGuardOutcome | null> {
+	const row = await db
+		.prepare(
+			`SELECT
+				c.type,
+				ac.body_markdown,
+				ac.body_html
+			FROM content_items c
+			LEFT JOIN article_content ac ON ac.content_id = c.id
+			WHERE c.id = ?
+			LIMIT 1`,
+		)
+		.bind(id)
+		.first<{
+			type: ContentType
+			body_markdown: string | null
+			body_html: string | null
+		}>()
+
+	if (!row || (row.type !== 'article' && row.type !== 'newsletter')) {
+		return null
+	}
+
+	return evaluateArticleBody(
+		{
+			body_markdown: row.body_markdown,
+			body_html: row.body_html,
+		},
+		{
+			source,
+			contentId: id,
+			requireBody: true,
+		},
+	)
+}
+
+export async function assertContentBodyValidForPublish(
+	db: D1Database,
+	id: string,
+	source: string,
+): Promise<void> {
+	const outcome = await evaluateContentBodyForPublish(db, id, source)
+	if (outcome && !outcome.ok) {
+		throw new PublishContentValidationError(outcome)
+	}
+}
+
+export async function publishContent(
+	db: D1Database,
+	id: string,
+	publishedAt: number,
+): Promise<void> {
+	await db
+		.prepare(
+			`UPDATE content_items SET status = 'published', published_at = ?, publish_at = NULL, updated_at = unixepoch() WHERE id = ?`,
+		)
+		.bind(publishedAt, id)
+		.run()
+}
+
+/**
+ * Atomically claim a SCHEDULED item for publishing.
+ *
+ * Performs the scheduled→published transition ONLY when the row is still
+ * `status = 'scheduled'`, and reports whether THIS call won the claim. This is
+ * the concurrency guard for the scheduled-publish sweep: when two cron runs
+ * overlap, both may SELECT the same due row, but only the first conditional
+ * UPDATE flips the status — the second sees `changes = 0` and must no-op
+ * (skipping the duplicate publish + duplicate published-revision write).
+ *
+ * Returns true if this call published the item, false if it was already taken.
+ */
+export async function claimScheduledForPublish(
+	db: D1Database,
+	id: string,
+	publishedAt: number,
+): Promise<boolean> {
+	const res = await db
+		.prepare(
+			`UPDATE content_items
+			 SET status = 'published', published_at = ?, publish_at = NULL, updated_at = unixepoch()
+			 WHERE id = ? AND status = 'scheduled'`,
+		)
+		.bind(publishedAt, id)
+		.run()
+	const changes = (res.meta as { changes?: number } | undefined)?.changes ?? 0
+	return changes > 0
+}
+
+export async function unpublishContent(db: D1Database, id: string): Promise<void> {
+	await db
+		.prepare(
+			`UPDATE content_items
+       SET status = 'draft',
+           published_at = NULL,
+           publish_at = NULL,
+           updated_at = unixepoch()
+       WHERE id = ?`,
+		)
+		.bind(id)
+		.run()
+}
+
+export async function duplicateContentItem(
+	db: D1Database,
+	sourceId: string,
+): Promise<{ id: string; slug: string } | null> {
+	const source = await getContentItem(db, sourceId)
+	if (!source) return null
+
+	const newId = crypto.randomUUID()
+	const newSlug = await ensureUniqueSlug(db, `${source.slug}-copy`)
+
+	// INSERT…SELECT copy #1 — content_items. The explicit column list is
+	// hand-maintained and MUST stay positionally aligned to the schema.
+	// created_at/updated_at are OMITTED so the copy gets fresh
+	// DEFAULT (unixepoch()) timestamps; status forced to 'draft', featured to
+	// 0, publish_at/published_at/published_revision_id to NULL. (inventory §6)
+	//
+	// SEO carries over (seo_title, seo_focus_keyword, seo_score, ai_og_image_id)
+	// — a duplicate should keep the SEO work already done on the source. But
+	// board_position is the source item's slot in the editorial board ordering;
+	// a fresh draft copy must NOT inherit it, so it is reset to NULL.
+	await db
+		.prepare(
+			`INSERT INTO content_items (
+				id, type, status, visibility, slug, title, seo_title, description, excerpt,
+				byline, channel, primary_topic, featured, author_id,
+				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
+				canonical_url, publish_at, published_at,
+				publish_tz, ai_locked_fields, published_revision_id,
+				seo_focus_keyword, seo_score, ai_og_image_id, board_position
+			)
+			SELECT
+				?, type, 'draft', visibility, ?, title || ' (Copy)', seo_title, description, excerpt,
+				byline, channel, primary_topic, 0, author_id,
+				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
+				canonical_url, NULL, NULL,
+				publish_tz, ai_locked_fields, NULL,
+				seo_focus_keyword, seo_score, ai_og_image_id, NULL
+			FROM content_items
+			WHERE id = ?`,
+		)
+		.bind(newId, newSlug, sourceId)
+		.run()
+
+	if (source.type === 'article' || source.type === 'newsletter') {
+		// INSERT…SELECT copy #2 — article_content. Body + editor takeaways + the
+		// generated faq_json carry across so the duplicate keeps its SEO/FAQ work.
+		await db
+			.prepare(
+				`INSERT INTO article_content (content_id, body_markdown, body_html, word_count, read_time_minutes, subtitle, editor_takeaways, faq_json)
+				 SELECT ?, body_markdown, body_html, word_count, read_time_minutes, subtitle, editor_takeaways, faq_json
+				 FROM article_content WHERE content_id = ?`,
+			)
+			.bind(newId, sourceId)
+			.run()
+	} else if (source.type === 'video') {
+		// INSERT…SELECT copy #3 — video_content. processing_state is
+		// hard-coded to 'ready' so a duplicated video is NOT re-queued to
+		// Foundry. (inventory §6)
+		await db
+			.prepare(
+				`INSERT INTO video_content (content_id, script, video_id, duration_seconds, thumbnail_image_id, processing_state)
+				 SELECT ?, script, video_id, duration_seconds, thumbnail_image_id, 'ready'
+				 FROM video_content WHERE content_id = ?`,
+			)
+			.bind(newId, sourceId)
+			.run()
+	} else if (source.type === 'podcast') {
+		await db
+			.prepare(
+				`INSERT INTO podcast_content (content_id, transcript, audio_r2_key, duration_seconds)
+				 SELECT ?, transcript, audio_r2_key, duration_seconds
+				 FROM podcast_content WHERE content_id = ?`,
+			)
+			.bind(newId, sourceId)
+			.run()
+	}
+
+	// INSERT…SELECT copy #4 — content_tag_links (carry the same tags).
+	await db
+		.prepare(
+			`INSERT INTO content_tag_links (content_id, tag_id)
+			 SELECT ?, tag_id FROM content_tag_links WHERE content_id = ?`,
+		)
+		.bind(newId, sourceId)
+		.run()
+
+	return { id: newId, slug: newSlug }
+}
+
+export async function createRevision(
+	db: D1Database,
+	contentId: string,
+	createdBy?: string | null,
+): Promise<void> {
+	const payload = await getContentSnapshot(db, contentId)
+	if (!payload) return
+	const revisionId = crypto.randomUUID()
+
+	await db
+		.prepare(
+			'INSERT INTO content_revisions (id, content_id, payload_json, created_at, created_by) VALUES (?, ?, ?, unixepoch(), ?)',
+		)
+		.bind(revisionId, contentId, JSON.stringify(payload), createdBy || null)
+		.run()
+
+	await db
+		.prepare('UPDATE content_items SET published_revision_id = ? WHERE id = ?')
+		.bind(revisionId, contentId)
+		.run()
+}
+
+export async function getContentSnapshot(
+	db: D1Database,
+	contentId: string,
+): Promise<Record<string, unknown> | null> {
+	const base = await db
+		.prepare('SELECT * FROM content_items WHERE id = ? LIMIT 1')
+		.bind(contentId)
+		.first<Record<string, unknown>>()
+
+	if (!base) return null
+
+	const type = base.type as ContentType
+	let content: Record<string, unknown> | null = null
+
+	if (type === 'article' || type === 'newsletter') {
+		content = await db
+			.prepare('SELECT * FROM article_content WHERE content_id = ? LIMIT 1')
+			.bind(contentId)
+			.first<Record<string, unknown>>()
+	}
+
+	if (type === 'video') {
+		content = await db
+			.prepare('SELECT * FROM video_content WHERE content_id = ? LIMIT 1')
+			.bind(contentId)
+			.first<Record<string, unknown>>()
+	}
+
+	if (type === 'podcast') {
+		content = await db
+			.prepare('SELECT * FROM podcast_content WHERE content_id = ? LIMIT 1')
+			.bind(contentId)
+			.first<Record<string, unknown>>()
+	}
+
+	const tags = await db
+		.prepare(
+			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ?',
+		)
+		.bind(contentId)
+		.all<{ slug: string }>()
+
+	const related = await db
+		.prepare(
+			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC',
+		)
+		.bind(contentId)
+		.all<{ related_id: string; rank: number; reason: string | null }>()
+
+	return {
+		item: base,
+		content,
+		tags: (tags.results || []).map((row) => row.slug),
+		related: related.results || [],
+	}
+}