@growth-labs/cms 0.1.0

package/src/routes/content.ts

@@ -0,0 +1,1753 @@
+// Content route handlers (WS7-07). Ported from fulcrum-labs/fronts
+// src/pages/api/v1/publisher/content/index.ts + [id].ts (inventory §3:
+// extract). Calls the already-extracted engine functions (createContent,
+// updateContentItem, scheduleContent, publishContent, unpublishContent,
+// duplicateContentItem, createRevision, evaluateContentBodyForPublish).
+//
+// Two Fronts couplings are removed:
+//   - authz: injected via config.authz.requirePublisher (NOT context.locals).
+//   - the Foundry article-takeaways dispatch (lib/foundry/article-takeaways.ts)
+//     is bead-08 glue, NOT yet extracted into the engine. So instead of
+//     hard-importing it, the publish + regenerate-takeaways actions call an
+//     OPTIONAL injected `dispatchTakeaways` hook (config). A site that wires the
+//     Foundry dispatcher gets the exact Fronts behavior; a site that omits it
+//     simply publishes without queuing takeaways. This keeps the package free
+//     of the Foundry/Hermes media glue (which lands with bead 08 + OD-CMS7).
+
+import { z } from 'zod'
+import { logActivity } from '../engine/activity-log.js'
+import { listContributors, setContributors } from '../engine/contributors.js'
+import type { D1Database } from '../engine/d1.js'
+import {
+	applyFoundryCallback,
+	type DispatchResult,
+	dispatchToFoundry,
+	type ProcessingState,
+	verifyHmac,
+} from '../engine/foundry-dispatch.js'
+import { evaluateArticleBody } from '../engine/publish-guard.js'
+import {
+	createContent,
+	createRevision,
+	duplicateContentItem,
+	evaluateContentBodyForPublish,
+	getContentItem,
+	getContentRelations,
+	publishContent,
+	scheduleContent,
+	unpublishContent,
+	updateContentItem,
+} from '../engine/publisher.js'
+import {
+	createRevisionWithDelta,
+	getRevision,
+	listRevisions,
+	restoreRevision,
+} from '../engine/revisions.js'
+import { recordSlugRedirect } from '../engine/slug-redirects.js'
+import { softDeleteContent } from '../engine/soft-delete.js'
+import type { ContentStatus } from '../schema/types.js'
+import { type ContentAction, canPerformContentAction } from './authz-matrix.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { json, type RouteContext, requireId } from './context.js'
+import type { DispatchWebhookHook } from './webhooks.js'
+
+export type { DispatchWebhookHook }
+
+/**
+ * Optional injected hook to dispatch article-takeaways generation to Foundry
+ * (Hermes). The package never imports the Foundry glue — the site supplies this
+ * (bead 08). `force` mirrors the Fronts dispatcher: skip when takeaways already
+ * exist unless forced.
+ */
+export type DispatchTakeawaysHook = (input: {
+	ctx: RouteContext
+	contentId: string
+	force: boolean
+}) => Promise<{ queued: boolean; correlationId?: string | null; reason?: string }>
+
+/**
+ * Optional injected hook to dispatch article-FAQ generation (P4 Task 7).
+ * Same shape as `DispatchTakeawaysHook` — the site supplies the impl; the
+ * package defines the hook contract + calls it in the publish action.
+ */
+export type DispatchFaqHook = (input: {
+	ctx: RouteContext
+	contentId: string
+	force: boolean
+}) => Promise<{ queued: boolean; correlationId?: string | null; reason?: string }>
+
+export interface PublishReadinessOutcome {
+	ready: boolean
+	state?: string | null
+	blockers?: string[]
+	message?: string
+	etaLabel?: string
+	checkedAt?: number
+	status?: number
+}
+
+/**
+ * Optional injected publish-readiness hook. Hosts use this to enforce
+ * site-specific prerequisites (for example video HLS/transcript/captions
+ * readiness) before the generic CMS lifecycle publishes an item.
+ */
+export type PublishReadinessHook = (input: {
+	ctx: RouteContext
+	contentId: string
+	type: ContentType
+	status: string
+}) => Promise<PublishReadinessOutcome>
+
+export interface ContentRouteConfig extends CmsRouteConfig {
+	/** Optional Foundry takeaways dispatcher (bead 08). Omit to disable. */
+	dispatchTakeaways?: DispatchTakeawaysHook
+	/** Optional FAQ enrichment dispatcher (P4 Task 7). Omit to disable. */
+	dispatchFaq?: DispatchFaqHook
+	/** Optional host-specific readiness guard. A not-ready result blocks publish. */
+	publishReadiness?: PublishReadinessHook
+	/**
+	 * Optional webhook dispatcher hook (P7 Task 9). Fired at each content
+	 * lifecycle transition (publish, unpublish, schedule, archive, create, etc.).
+	 * A missing hook is silently skipped — the lifecycle action still succeeds
+	 * (mirrors the dispatchTakeaways pattern). The hook reads the HMAC secret
+	 * from ctx.env (Secrets Store binding) — never from D1.
+	 */
+	dispatchWebhook?: DispatchWebhookHook
+	/**
+	 * Active workspace id — used to scope the activity log write on publish.
+	 * Matches the ShellRouteConfig.activeWorkspaceId seam. Defaults to 'default'
+	 * when absent so callers without a workspace concept still produce a scoped row.
+	 */
+	activeWorkspaceId?: string
+}
+
+const PUBLISH_TIMEZONE_FALLBACK = 'Europe/Paris'
+const LOCAL_DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
+
+type ContentType = 'article' | 'video' | 'podcast' | 'newsletter'
+
+/**
+ * Map a content `action` verb (the ?action= query value) to the capability the
+ * 5-role matrix gates it on. Lifecycle/destructive verbs require publish-level
+ * authority; status/duplicate/snapshot edits are writes; media-pipeline dispatch
+ * verbs require media_pipeline. publish on a video/podcast resolves to
+ * publish_video so the producer role can ship video.
+ */
+function mapActionToCapability(action: string | null, type: ContentType): ContentAction {
+	switch (action) {
+		case 'publish':
+			return type === 'video' || type === 'podcast' ? 'publish_video' : 'publish'
+		case 'unpublish':
+		case 'archive':
+		case 'unschedule':
+			return 'publish'
+		case 'schedule':
+			return 'schedule'
+		case 'trash':
+			return 'trash'
+		case 'dispatch-to-foundry':
+		case 'regenerate-takeaways':
+		case 'regenerate-faq':
+			return 'media'
+		default:
+			// duplicate / set-status / snapshot and any unknown verb → write-level.
+			return 'write'
+	}
+}
+
+const parseTypes = (value: string | null): ContentType[] | undefined => {
+	if (!value) return undefined
+	const allowed: ContentType[] = ['article', 'video', 'podcast', 'newsletter']
+	const parts = value
+		.split(',')
+		.map((item) => item.trim())
+		.filter(Boolean) as ContentType[]
+	const filtered = parts.filter((part) => allowed.includes(part))
+	return filtered.length > 0 ? filtered : undefined
+}
+
+const parseStatus = (value: string | null): ContentStatus | undefined => {
+	if (!value) return undefined
+	const allowed: ContentStatus[] = ['draft', 'scheduled', 'review', 'published', 'archived']
+	return allowed.includes(value as ContentStatus) ? (value as ContentStatus) : undefined
+}
+
+const parseCursor = (
+	cursor: string | null | undefined,
+): { updatedAt: number; id: string } | null => {
+	if (!cursor) return null
+	const [timestamp, id] = cursor.split(':')
+	const updatedAt = Number(timestamp)
+	if (!Number.isFinite(updatedAt) || !id) return null
+	return { updatedAt, id }
+}
+
+function normalizeUnixSeconds(value: unknown): number | null {
+	if (value === null || value === undefined || value === '') return null
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) return null
+		return value > 1e11 ? Math.floor(value / 1000) : value
+	}
+	if (typeof value !== 'string') return null
+	const trimmed = value.trim()
+	if (!trimmed) return null
+	const numeric = Number(trimmed)
+	if (Number.isFinite(numeric)) return numeric > 1e11 ? Math.floor(numeric / 1000) : numeric
+	const parsedMs = Date.parse(trimmed)
+	if (!Number.isFinite(parsedMs)) return null
+	return Math.floor(parsedMs / 1000)
+}
+
+function unixSecondsToIso(value: unknown): string | null {
+	const seconds = normalizeUnixSeconds(value)
+	if (seconds === null) return null
+	const date = new Date(seconds * 1000)
+	return Number.isFinite(date.getTime()) ? date.toISOString() : null
+}
+
+// A category/topic enum becomes a site-supplied list; default to any string.
+function slugEnum(values: readonly string[] | null) {
+	return values && values.length > 0
+		? z.enum([values[0], ...values.slice(1)] as [string, ...string[]])
+		: z.string().min(1)
+}
+
+function buildSchemas(resolved: ReturnType<typeof resolveConfig>) {
+	const category = slugEnum(resolved.primaryCategorySlugs)
+	const topic = slugEnum(resolved.primaryTopicSlugs)
+
+	const BaseSchema = z.object({
+		slug: z.string().min(3),
+		title: z.string().min(3),
+		seoTitle: z.string().optional().nullable(),
+		description: z.string().optional().nullable(),
+		excerpt: z.string().optional().nullable(),
+		byline: z.string().optional().nullable(),
+		primaryCategory: category.default(resolved.defaultPrimaryCategory),
+		primaryTopic: topic.default(resolved.defaultPrimaryTopic),
+		featured: z.boolean().optional(),
+		visibility: z.enum(['free', 'premium']).optional(),
+		authorId: z.string().optional().nullable(),
+		heroImageId: z.string().optional().nullable(),
+		heroImageAlt: z.string().optional().nullable(),
+		heroImageCaption: z.string().optional().nullable(),
+		socialImageId: z.string().optional().nullable(),
+		canonicalUrl: z.string().url().optional().nullable(),
+		tags: z.array(z.string()).optional(),
+	})
+
+	const CreateSchema = z.discriminatedUnion('type', [
+		BaseSchema.extend({
+			type: z.literal('article'),
+			content: z.object({
+				bodyMarkdown: z.string().min(1),
+				bodyHtml: z.string().optional().nullable(),
+				subtitle: z.string().optional().nullable(),
+				wordCount: z.number().int().optional().nullable(),
+				readTimeMinutes: z.number().int().optional().nullable(),
+				editorTakeaways: z.array(z.string().min(1)).max(4).optional().nullable(),
+			}),
+		}),
+		BaseSchema.extend({
+			type: z.literal('video'),
+			content: z.object({
+				script: z.string().default(''),
+				videoId: z.string().min(1),
+				durationSeconds: z.number().int().optional().nullable(),
+				thumbnailImageId: z.string().optional().nullable(),
+				processingSourceUrl: z.string().url().optional().nullable(),
+				processingSourceKind: z.string().min(1).optional().nullable(),
+			}),
+		}),
+		BaseSchema.extend({
+			type: z.literal('podcast'),
+			content: z.object({
+				// Empty allowed: a podcast is created as a draft with audio uploaded
+				// but no transcript yet — the transcription pipeline fills it async
+				// (Foundry callback hydrates podcast_content.transcript later). Mirrors
+				// the video `script` default-empty pattern above.
+				transcript: z.string().default(''),
+				audioR2Key: z.string().min(1),
+				durationSeconds: z.number().int().optional().nullable(),
+			}),
+		}),
+		BaseSchema.extend({
+			type: z.literal('newsletter'),
+			content: z.object({
+				bodyMarkdown: z.string().min(1),
+				bodyHtml: z.string().optional().nullable(),
+				subtitle: z.string().optional().nullable(),
+				wordCount: z.number().int().optional().nullable(),
+				readTimeMinutes: z.number().int().optional().nullable(),
+				editorTakeaways: z.array(z.string().min(1)).max(4).optional().nullable(),
+			}),
+		}),
+	])
+
+	const RelationSchema = z.object({
+		relatedId: z.string().min(1),
+		rank: z.number().int().min(0),
+		reason: z.string().optional().nullable(),
+	})
+
+	const UpdateSchema = z.object({
+		slug: z.string().min(3).optional(),
+		title: z.string().min(3).optional(),
+		seoTitle: z.string().optional().nullable(),
+		description: z.string().optional().nullable(),
+		excerpt: z.string().optional().nullable(),
+		byline: z.string().optional().nullable(),
+		primaryCategory: category.optional().nullable(),
+		primaryTopic: topic.optional().nullable(),
+		featured: z.boolean().optional(),
+		visibility: z.enum(['free', 'premium']).optional(),
+		authorId: z.string().optional().nullable(),
+		heroImageId: z.string().optional().nullable(),
+		heroImageAlt: z.string().optional().nullable(),
+		heroImageCaption: z.string().optional().nullable(),
+		socialImageId: z.string().optional().nullable(),
+		canonicalUrl: z.string().url().optional().nullable(),
+		tags: z.array(z.string()).optional(),
+		content: z.record(z.string(), z.any()).optional(),
+		relations: z.array(RelationSchema).optional(),
+		aiLockedFields: z.array(z.string()).optional(),
+		/** SEO focus keyword (P3 SEO tab — migration 0004 column). */
+		seoFocusKeyword: z.string().optional().nullable(),
+	})
+
+	return { CreateSchema, UpdateSchema }
+}
+
+const ArticleContentUpdateSchema = z.object({
+	bodyMarkdown: z.string().optional(),
+	bodyHtml: z.string().optional().nullable(),
+	subtitle: z.string().optional().nullable(),
+	wordCount: z.number().int().optional().nullable(),
+	readTimeMinutes: z.number().int().optional().nullable(),
+	editorTakeaways: z.array(z.string().min(1)).max(4).optional().nullable(),
+})
+
+const VideoContentUpdateSchema = z.object({
+	script: z.string().optional(),
+	videoId: z.string().optional(),
+	durationSeconds: z.number().int().optional().nullable(),
+	thumbnailImageId: z.string().optional().nullable(),
+	processingSourceUrl: z.string().url().optional().nullable(),
+	processingSourceKind: z.string().min(1).optional().nullable(),
+})
+
+const PodcastContentUpdateSchema = z.object({
+	transcript: z.string().optional(),
+	audioR2Key: z.string().optional(),
+	durationSeconds: z.number().int().optional().nullable(),
+})
+
+function getContentUpdateSchema(type: string) {
+	switch (type) {
+		case 'article':
+		case 'newsletter':
+			return ArticleContentUpdateSchema
+		case 'video':
+			return VideoContentUpdateSchema
+		case 'podcast':
+			return PodcastContentUpdateSchema
+		default:
+			return null
+	}
+}
+
+const ScheduleSchema = z
+	.object({
+		publishAt: z.string().min(1).optional().nullable(),
+		publishAtLocal: z.string().min(1).optional().nullable(),
+		timezone: z.string().optional().nullable(),
+	})
+	.refine((value) => Boolean(value.publishAt || value.publishAtLocal), {
+		message: 'publishAt or publishAtLocal is required',
+		path: ['publishAt'],
+	})
+
+// Bulk operations schema — the Library bulk-action bar sends one of these.
+// publish/schedule/unpublish use their own guarded action routes; bulk schedule
+// is a convenience wrapper only (no body-validation gate — use the per-item
+// action for pre-publish lint).
+const BulkSchema = z.discriminatedUnion('op', [
+	z.object({ op: z.literal('trash'), ids: z.array(z.string().min(1)).min(1) }),
+	z.object({
+		op: z.literal('topic'),
+		ids: z.array(z.string().min(1)).min(1),
+		topic: z.string().min(1),
+	}),
+	z.object({
+		op: z.literal('schedule'),
+		ids: z.array(z.string().min(1)).min(1),
+		publishAt: z.string().min(1),
+	}),
+])
+
+// set-status only allows the safe non-publish transitions.
+// publish/schedule keep their dedicated guarded action routes.
+const SetStatusSchema = z.object({
+	status: z.enum(['draft', 'review']),
+})
+
+// Contributors PUT body schema (P3 Task 3).
+const ContributorItemSchema = z.object({
+	authorId: z.string().min(1),
+	role: z.string().optional().nullable(),
+	position: z.number().int().min(0).default(0),
+})
+const ContributorsReplaceSchema = z.object({
+	contributors: z.array(ContributorItemSchema),
+})
+
+// --- timezone-aware local-datetime parsing (ported verbatim) --------------
+
+type LocalDateTimeParts = { year: number; month: number; day: number; hour: number; minute: number }
+
+function parseLocalDateTime(value: string): LocalDateTimeParts | null {
+	const match = LOCAL_DATE_TIME_RE.exec(value)
+	if (!match) return null
+	const [, y, m, d, h, min] = match
+	const parts: LocalDateTimeParts = {
+		year: Number.parseInt(y, 10),
+		month: Number.parseInt(m, 10),
+		day: Number.parseInt(d, 10),
+		hour: Number.parseInt(h, 10),
+		minute: Number.parseInt(min, 10),
+	}
+	if (
+		!Number.isInteger(parts.year) ||
+		parts.month < 1 ||
+		parts.month > 12 ||
+		parts.day < 1 ||
+		parts.day > 31 ||
+		parts.hour < 0 ||
+		parts.hour > 23 ||
+		parts.minute < 0 ||
+		parts.minute > 59
+	) {
+		return null
+	}
+	const dateCheck = new Date(Date.UTC(parts.year, parts.month - 1, parts.day))
+	if (
+		dateCheck.getUTCFullYear() !== parts.year ||
+		dateCheck.getUTCMonth() + 1 !== parts.month ||
+		dateCheck.getUTCDate() !== parts.day
+	) {
+		return null
+	}
+	return parts
+}
+
+function getZonedParts(instantMs: number, timeZone: string): LocalDateTimeParts | null {
+	const formatter = new Intl.DateTimeFormat('en-US', {
+		timeZone,
+		hour12: false,
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	})
+	const values = { year: '', month: '', day: '', hour: '', minute: '', second: '' }
+	for (const part of formatter.formatToParts(new Date(instantMs))) {
+		if (part.type in values) values[part.type as keyof typeof values] = part.value
+	}
+	const year = Number.parseInt(values.year, 10)
+	const month = Number.parseInt(values.month, 10)
+	const day = Number.parseInt(values.day, 10)
+	const hour = Number.parseInt(values.hour, 10)
+	const minute = Number.parseInt(values.minute, 10)
+	if (![year, month, day, hour, minute].every(Number.isFinite)) return null
+	return { year, month, day, hour, minute }
+}
+
+function isValidTimeZone(timeZone: string): boolean {
+	try {
+		new Intl.DateTimeFormat('en-US', { timeZone }).format(new Date())
+		return true
+	} catch {
+		return false
+	}
+}
+
+function getTimeZoneOffsetMs(instantMs: number, timeZone: string): number | null {
+	const zoned = getZonedParts(instantMs, timeZone)
+	if (!zoned) return null
+	const asUtc = Date.UTC(zoned.year, zoned.month - 1, zoned.day, zoned.hour, zoned.minute, 0)
+	return asUtc - instantMs
+}
+
+function parseLocalDateTimeInZoneToUnixSeconds(value: string, timeZone: string): number | null {
+	const target = parseLocalDateTime(value)
+	if (!target) return null
+	const targetUtcMs = Date.UTC(
+		target.year,
+		target.month - 1,
+		target.day,
+		target.hour,
+		target.minute,
+		0,
+	)
+	let candidateMs = targetUtcMs
+	for (let i = 0; i < 5; i += 1) {
+		const offsetMs = getTimeZoneOffsetMs(candidateMs, timeZone)
+		if (offsetMs === null) return null
+		const next = targetUtcMs - offsetMs
+		if (Math.abs(next - candidateMs) < 1000) {
+			candidateMs = next
+			break
+		}
+		candidateMs = next
+	}
+	const resolved = getZonedParts(candidateMs, timeZone)
+	if (
+		!resolved ||
+		resolved.year !== target.year ||
+		resolved.month !== target.month ||
+		resolved.day !== target.day ||
+		resolved.hour !== target.hour ||
+		resolved.minute !== target.minute
+	) {
+		return null
+	}
+	return Math.floor(candidateMs / 1000)
+}
+
+// --- read-side payload helpers (ported verbatim) --------------------------
+
+async function getContentPayload(ctx: RouteContext, type: string, id: string) {
+	if (type === 'article' || type === 'newsletter') {
+		return ctx.db
+			.prepare(
+				`SELECT body_markdown, body_html, word_count, read_time_minutes, subtitle,
+					ai_takeaways, ai_takeaways_at, ai_takeaways_model, editor_takeaways,
+					ai_takeaways_correlation_id
+				FROM article_content WHERE content_id = ? LIMIT 1`,
+			)
+			.bind(id)
+			.first()
+	}
+	if (type === 'video') {
+		return ctx.db
+			.prepare(
+				`SELECT script, video_id, duration_seconds, thumbnail_image_id, processing_state,
+					processing_correlation_id, processing_started_at, processing_completed_at,
+					processing_last_event_at, processing_error, processing_source_url,
+					processing_source_kind, source_fetched, transcript_ready, hls_ready,
+					transcript_url, hls_manifest_url, hls_poster_url
+				FROM video_content WHERE content_id = ? LIMIT 1`,
+			)
+			.bind(id)
+			.first()
+	}
+	if (type === 'podcast') {
+		return ctx.db
+			.prepare(
+				'SELECT transcript, audio_r2_key, duration_seconds FROM podcast_content WHERE content_id = ? LIMIT 1',
+			)
+			.bind(id)
+			.first()
+	}
+	return null
+}
+
+async function getContentTags(ctx: RouteContext, id: string): Promise<string[]> {
+	const result = await ctx.db
+		.prepare(
+			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ? ORDER BY t.label ASC',
+		)
+		.bind(id)
+		.all<{ slug: string }>()
+	return (result.results || []).map((row) => row.slug)
+}
+
+async function getMediaAssetUrls(db: D1Database, ids: string[]): Promise<Record<string, string>> {
+	const uniqueIds = Array.from(new Set(ids.filter(Boolean)))
+	if (uniqueIds.length === 0) return {}
+	const placeholders = uniqueIds.map(() => '?').join(',')
+	const result = await db
+		.prepare(`SELECT id, public_url, url FROM media_assets WHERE id IN (${placeholders})`)
+		.bind(...uniqueIds)
+		.all<{ id: string; public_url: string | null; url: string | null }>()
+
+	const urls: Record<string, string> = {}
+	for (const row of result.results ?? []) {
+		const url = row.public_url || row.url
+		if (url) urls[row.id] = url
+	}
+	return urls
+}
+
+async function readJson(ctx: RouteContext): Promise<unknown> {
+	return ctx.request.json().catch(() => null)
+}
+
+export interface ContentRouteHandlers {
+	/** GET /content — cursor-paginated list (q, author, status, types filters; excludes deleted). */
+	list(ctx: RouteContext): Promise<Response>
+	/** GET /content/counts — status-tab counts for the Library (excludes deleted; includes derived processing). */
+	counts(ctx: RouteContext): Promise<Response>
+	/** POST /content/bulk — bulk ops: trash | topic | schedule. */
+	bulk(ctx: RouteContext): Promise<Response>
+	/** POST /content — create. */
+	create(ctx: RouteContext): Promise<Response>
+	/** GET /content/:id — read (item + content + tags + relations). */
+	get(ctx: RouteContext): Promise<Response>
+	/** PATCH /content/:id — update (with pre-publish body lint on article bodies). */
+	update(ctx: RouteContext): Promise<Response>
+	/**
+	 * POST /content/:id?action=... — lifecycle actions: schedule | publish |
+	 * regenerate-takeaways | unpublish | archive | unschedule | duplicate |
+	 * set-status (draft|review only) | snapshot (autosave revision).
+	 */
+	action(ctx: RouteContext): Promise<Response>
+	/**
+	 * POST /content/:id/seo-score — real-time draft SEO score (P3 SEO tab).
+	 * Reads the live row + body, merges optional JSON body overrides
+	 * ({ title?, seoTitle?, description?, focusKeyword?, bodyMarkdown? }),
+	 * runs the injected SeoProvider and returns { score, checks }.
+	 * Persists nothing (read-only scoring).
+	 */
+	seoScore(ctx: RouteContext): Promise<Response>
+	/**
+	 * GET /content/:id/contributors — list co-authors ordered by position, joined
+	 * to author name + avatar. Returns { contributors: [...] }.
+	 */
+	contributorsList(ctx: RouteContext): Promise<Response>
+	/**
+	 * PUT /content/:id/contributors — fully replace the contributor list.
+	 * Body: { contributors: [{ authorId, role?, position }] }.
+	 * Returns { contributors: [...] } (the new list after replace).
+	 */
+	contributorsReplace(ctx: RouteContext): Promise<Response>
+	/**
+	 * GET /content/:id/revisions — list all revisions newest-first.
+	 * Returns { revisions: [{ id, createdAt, createdBy, wordsAdded, wordsRemoved, tag }] }.
+	 * 404 when the content item does not exist.
+	 */
+	revisionsList(ctx: RouteContext): Promise<Response>
+	/**
+	 * GET /content/:id/revisions/:rev — get a single revision's summary + full payload.
+	 * Returns { summary, payload }. 404 when not found.
+	 */
+	revisionGet(ctx: RouteContext): Promise<Response>
+	/**
+	 * POST /content/foundry-callback — machine-to-machine Foundry pipeline callback.
+	 * Verifies the HMAC-SHA256 signature in `X-Foundry-Signature` against
+	 * `ctx.env.FOUNDRY_HMAC_SECRET`, then advances the video_content processing
+	 * state machine via `applyFoundryCallback`. Guarded by HMAC only (not
+	 * `requirePublisher` — this is a machine callback, not a user action).
+	 * Returns { ok: true } on success, { ok: false } on dedup/token mismatch,
+	 * 401 on bad signature.
+	 */
+	foundryCallback(ctx: RouteContext): Promise<Response>
+	/**
+	 * POST /content/:id/revisions/:rev/restore — restore the content to a revision snapshot.
+	 * Returns { restored: true }. 404 when the revision is not found.
+	 * IMPORTANT: restore rolls back content fields but NEVER changes publication state
+	 * (status / published_at / published_revision_id).
+	 */
+	revisionRestore(ctx: RouteContext): Promise<Response>
+}
+
+export function createContentRoutes(config: ContentRouteConfig): ContentRouteHandlers {
+	const resolved = resolveConfig(config)
+	const { CreateSchema, UpdateSchema } = buildSchemas(resolved)
+	const dispatchTakeaways = config.dispatchTakeaways
+	const dispatchFaq = config.dispatchFaq
+	const dispatchWebhook = config.dispatchWebhook
+	const publishReadiness = config.publishReadiness
+	const activeWorkspaceId = config.activeWorkspaceId ?? 'default'
+
+	async function maybeDispatchPodcastToFoundry(
+		ctx: RouteContext,
+		contentId: string,
+	): Promise<DispatchResult | null> {
+		if (!resolved.hooks.foundryVideo) return null
+		const row = await ctx.db
+			.prepare(
+				`SELECT transcript, audio_r2_key, processing_trigger_token
+				FROM podcast_content
+				WHERE content_id = ?
+				LIMIT 1`,
+			)
+			.bind(contentId)
+			.first<{
+				transcript: string | null
+				audio_r2_key: string | null
+				processing_trigger_token: string | null
+			}>()
+		const audioR2Key = row?.audio_r2_key?.trim() ?? ''
+		if (!audioR2Key) return null
+		if (row?.processing_trigger_token?.trim()) return null
+		if (row?.transcript?.trim()) return null
+		return dispatchToFoundry(ctx.db, contentId, resolved.hooks.foundryVideo)
+	}
+
+	/**
+	 * Fire the optional dispatchWebhook hook for a lifecycle transition.
+	 *
+	 * Wrapped in try/catch so a webhook dispatch failure NEVER fails the action
+	 * — identical guard pattern to dispatchTakeaways / logActivity.
+	 * When no hook is injected this is a no-op (no 501, no error).
+	 */
+	async function fireWebhook(
+		ctx: RouteContext,
+		eventType: string,
+		data: Record<string, unknown>,
+	): Promise<void> {
+		if (!dispatchWebhook) return
+		try {
+			await dispatchWebhook(ctx, {
+				eventType,
+				workspaceId: activeWorkspaceId,
+				data,
+			})
+		} catch (err) {
+			console.error(`[cms] dispatchWebhook(${eventType}) failed`, err)
+		}
+	}
+
+	/**
+	 * Capability gate for a content mutation. Enforces the 5-role matrix WITH the
+	 * contributor/producer ownership predicate (canPerformContentAction).
+	 *
+	 * When the host wires the role seam (authz.getUser), this resolves the actor's
+	 * role + subject and checks the action against the content's author. The launch
+	 * roster (owner/senior_editor/editor) is NEVER ownership-restricted, so editors
+	 * keep full editorial. contributor/producer are gated to their own/assigned
+	 * content and blocked from publish/destructive actions.
+	 *
+	 * `contentAuthorId` is the content_items.author_id (the host maps an authored
+	 * row to the actor's subject; the package compares the two for ownership).
+	 *
+	 * Backwards compatible: when authz.getUser is absent (host has not wired the
+	 * role layer) this falls back to the flat requirePublisher gate.
+	 */
+	async function requireContentAction(
+		ctx: RouteContext,
+		action: ContentAction,
+		contentAuthorId: string | null,
+	): Promise<Response | null> {
+		// Role seam not wired → flat publisher gate (legacy hosts).
+		if (!resolved.authz.getUser) {
+			return resolved.authz.requirePublisher(ctx)
+		}
+		const user = await resolved.authz.getUser(ctx)
+		if (!user) return json({ error: 'Unauthorized' }, 401)
+		const actorSubject = user.subject ?? ctx.userId ?? null
+		const allowed = canPerformContentAction(
+			user.role,
+			{ actorSubject: actorSubject ?? '', contentAuthorId },
+			action,
+		)
+		if (!allowed) {
+			return json({ error: 'Forbidden', action, role: user.role }, 403)
+		}
+		return null
+	}
+
+	return {
+		async list(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const url = new URL(ctx.request.url)
+			const limit = Math.min(Number(url.searchParams.get('limit') || '20'), 50)
+			const status = parseStatus(url.searchParams.get('status'))
+			const types = parseTypes(url.searchParams.get('types'))
+			const cursor = parseCursor(url.searchParams.get('cursor'))
+			const q = url.searchParams.get('q') || null
+			const author = url.searchParams.get('author') || null
+
+			const bindings: unknown[] = []
+			// Always exclude soft-deleted rows (migration 0002 added deleted_at).
+			let where = 'c.deleted_at IS NULL'
+			if (status) {
+				where += ' AND c.status = ?'
+				bindings.push(status)
+			}
+			if (types && types.length > 0) {
+				where += ` AND c.type IN (${types.map(() => '?').join(',')})`
+				bindings.push(...types)
+			}
+			if (q) {
+				where += ' AND (c.title LIKE ? OR c.slug LIKE ?)'
+				const pattern = `%${q}%`
+				bindings.push(pattern, pattern)
+			}
+			if (author) {
+				where += ' AND c.author_id = ?'
+				bindings.push(author)
+			}
+			if (cursor) {
+				where += ' AND (c.updated_at < ? OR (c.updated_at = ? AND c.id < ?))'
+				bindings.push(cursor.updatedAt, cursor.updatedAt, cursor.id)
+			}
+			bindings.push(limit + 1)
+
+			// LEFT JOIN video_content so each row carries its processing_state
+			// (null for non-video rows). The UI's StatusPill derives the
+			// "processing" pseudo-status from this; without it the field is
+			// undefined client-side and `processingState !== null` is true for
+			// EVERY row, mis-stamping all rows as PROCESSING. Mirrors the JOIN the
+			// counts handler below already uses.
+			const query = `
+				SELECT c.id, c.type, c.status, c.slug, c.title, c.visibility, c.featured,
+					c.publish_at, c.published_at, c.updated_at, c.author_id,
+					a.slug AS author_slug, a.name AS author_name,
+					vc.processing_state AS processing_state
+				FROM content_items c
+				LEFT JOIN authors a ON a.id = c.author_id
+				LEFT JOIN video_content vc ON vc.content_id = c.id
+				WHERE ${where}
+				ORDER BY c.updated_at DESC, c.id DESC
+				LIMIT ?`
+
+			const result = await ctx.db
+				.prepare(query)
+				.bind(...bindings)
+				.all<{
+					id: string
+					type: ContentType
+					status: ContentStatus
+					slug: string
+					title: string
+					visibility: 'free' | 'premium'
+					featured: number | null
+					publish_at: number | null
+					published_at: number | null
+					updated_at: number | null
+					author_id: string | null
+					author_slug: string | null
+					author_name: string | null
+					processing_state: string | null
+				}>()
+
+			const rows = result.results || []
+			const hasMore = rows.length > limit
+			const sliced = hasMore ? rows.slice(0, limit) : rows
+			const last = sliced[sliced.length - 1]
+			const lastUpdatedAt = last ? normalizeUnixSeconds(last.updated_at) : null
+			const nextCursor = last && lastUpdatedAt !== null ? `${lastUpdatedAt}:${last.id}` : null
+
+			const items = sliced.map((row) => ({
+				...row,
+				featured: Boolean(row.featured),
+				authorId: row.author_id ?? null,
+				authorSlug: row.author_slug ?? null,
+				authorName: row.author_name ?? null,
+				processingState: row.processing_state ?? null,
+				publishAt: unixSecondsToIso(row.publish_at),
+				publishedAt: unixSecondsToIso(row.published_at),
+				updatedAt: unixSecondsToIso(row.updated_at),
+			}))
+
+			return json({ items, nextCursor })
+		},
+
+		async counts(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			// Count non-deleted items grouped by status.
+			// "processing" is a derived pseudo-status: video rows whose
+			// processing_state is NOT in ('ready','failed') — a mid-flight
+			// Foundry pipeline job. It is NOT a value in the content_items.status
+			// CHECK enum (draft|scheduled|review|published|archived).
+			const rows = await ctx.db
+				.prepare(
+					`SELECT
+						COUNT(*) AS total,
+						SUM(CASE WHEN c.status = 'draft' THEN 1 ELSE 0 END) AS draft,
+						SUM(CASE WHEN c.status = 'scheduled' THEN 1 ELSE 0 END) AS scheduled,
+						SUM(CASE WHEN c.status = 'review' THEN 1 ELSE 0 END) AS review,
+						SUM(CASE WHEN c.status = 'published' THEN 1 ELSE 0 END) AS published,
+						SUM(CASE WHEN vc.processing_state IS NOT NULL
+							AND vc.processing_state NOT IN ('ready','failed')
+							THEN 1 ELSE 0 END) AS processing
+					FROM content_items c
+					LEFT JOIN video_content vc ON vc.content_id = c.id
+					WHERE c.deleted_at IS NULL`,
+				)
+				.first<{
+					total: number
+					draft: number
+					scheduled: number
+					review: number
+					published: number
+					processing: number
+				}>()
+
+			return json({
+				counts: {
+					all: rows?.total ?? 0,
+					draft: rows?.draft ?? 0,
+					scheduled: rows?.scheduled ?? 0,
+					review: rows?.review ?? 0,
+					published: rows?.published ?? 0,
+					processing: rows?.processing ?? 0,
+				},
+			})
+		},
+
+		async bulk(ctx) {
+			const parsed = BulkSchema.safeParse(await readJson(ctx))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+
+			const { op, ids } = parsed.data
+
+			// Bulk ops act across many (cross-author) items → require publish-level
+			// authority (publish_others_draft). contentAuthorId null forces the
+			// stricter bar, blocking contributor/producer; editors+ pass.
+			const bulkAction: ContentAction =
+				op === 'trash' ? 'trash' : op === 'schedule' ? 'schedule' : 'publish'
+			const denied = await requireContentAction(ctx, bulkAction, null)
+			if (denied) return denied
+
+			if (op === 'trash') {
+				for (const id of ids) {
+					await softDeleteContent(ctx.db, id)
+				}
+				return json({ trashed: ids })
+			}
+
+			if (op === 'topic') {
+				const { topic } = parsed.data
+				for (const id of ids) {
+					await ctx.db
+						.prepare(
+							'UPDATE content_items SET primary_topic = ?, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NULL',
+						)
+						.bind(topic, id)
+						.run()
+				}
+				return json({ updated: ids })
+			}
+
+			if (op === 'schedule') {
+				const { publishAt } = parsed.data
+				const publishAtMs = Date.parse(publishAt)
+				if (!Number.isFinite(publishAtMs)) {
+					return json({ error: 'Invalid publishAt' }, 400)
+				}
+				const publishAtSeconds = Math.floor(publishAtMs / 1000)
+				for (const id of ids) {
+					await scheduleContent(ctx.db, id, publishAtSeconds)
+				}
+				return json({ scheduled: ids })
+			}
+
+			// Exhaustive – the discriminated union above covers all ops.
+			return json({ error: 'Unhandled op' }, 400)
+		},
+
+		async create(ctx) {
+			// Create = write a new draft the actor authors. Pass the actor's own
+			// subject as the content author so the ownership predicate treats it as
+			// own content (contributor/producer may create their own drafts).
+			const actor = resolved.authz.getUser ? await resolved.authz.getUser(ctx) : null
+			const ownAuthor = actor?.subject ?? ctx.userId ?? null
+			const denied = await requireContentAction(ctx, 'write', ownAuthor)
+			if (denied) return denied
+
+			const parsed = CreateSchema.safeParse(await readJson(ctx))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+
+			const created = await createContent(ctx.db, parsed.data)
+			const podcastDispatch =
+				parsed.data.type === 'podcast' ? await maybeDispatchPodcastToFoundry(ctx, created.id) : null
+
+			// Fire content.created webhook (lifecycle transition).
+			await fireWebhook(ctx, 'content.created', {
+				id: created.id,
+				slug: created.slug,
+				type: parsed.data.type,
+			})
+
+			return json(
+				{
+					id: created.id,
+					slug: created.slug,
+					podcastFoundryQueued: Boolean(podcastDispatch),
+					podcastFoundryCorrelationId: podcastDispatch?.correlationId ?? null,
+				},
+				201,
+			)
+		},
+
+		async get(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			const item = await getContentItem(ctx.db, id)
+			if (!item) return json({ error: 'Not found' }, 404)
+
+			const [content, tags, relations, author] = await Promise.all([
+				getContentPayload(ctx, item.type, id),
+				getContentTags(ctx, id),
+				getContentRelations(ctx.db, id),
+				item.author_id
+					? ctx.db
+							.prepare('SELECT name, slug FROM authors WHERE id = ? LIMIT 1')
+							.bind(item.author_id)
+							.first<{ name: string | null; slug: string | null }>()
+					: Promise.resolve(null),
+			])
+			const contentRecord = content as Record<string, unknown> | null
+			const thumbnailImageId =
+				typeof contentRecord?.thumbnail_image_id === 'string'
+					? contentRecord.thumbnail_image_id
+					: null
+			const mediaUrls = await getMediaAssetUrls(
+				ctx.db,
+				[item.hero_image_id, thumbnailImageId].filter((value): value is string => Boolean(value)),
+			)
+			const heroImageUrl = item.hero_image_id ? (mediaUrls[item.hero_image_id] ?? null) : null
+			const thumbnailImageUrl = thumbnailImageId ? (mediaUrls[thumbnailImageId] ?? null) : null
+			const itemWithMedia = {
+				...item,
+				hero_image_url: heroImageUrl,
+				author_name: author?.name ?? null,
+				author_slug: author?.slug ?? null,
+			}
+			const contentWithMedia = contentRecord
+				? {
+						...contentRecord,
+						...(thumbnailImageId ? { thumbnail_image_url: thumbnailImageUrl } : {}),
+					}
+				: content
+
+			const aiLockedFields: string[] = (() => {
+				try {
+					return JSON.parse(item.ai_locked_fields || '[]')
+				} catch {
+					return []
+				}
+			})()
+
+			return json({
+				item: itemWithMedia,
+				content: contentWithMedia,
+				tags,
+				relations,
+				aiLockedFields,
+			})
+		},
+
+		async update(ctx) {
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			const existing = await getContentItem(ctx.db, id)
+			if (!existing) return json({ error: 'Not found' }, 404)
+
+			// Edit = write; contributor/producer gated to their own content.
+			const denied = await requireContentAction(ctx, 'write', existing.author_id)
+			if (denied) return denied
+
+			const parsed = UpdateSchema.safeParse(await readJson(ctx))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+
+			if (parsed.data.content !== undefined) {
+				const contentSchema = getContentUpdateSchema(existing.type)
+				if (!contentSchema) return json({ error: 'Invalid content type' }, 400)
+
+				const contentParsed = contentSchema.safeParse(parsed.data.content)
+				if (!contentParsed.success) {
+					return json({ error: 'Invalid request', details: contentParsed.error.flatten() }, 400)
+				}
+				parsed.data.content = contentParsed.data
+
+				// Pre-publish content lint: refuse to overwrite an article body with
+				// content that contains known formatting artifacts. Draft saves run
+				// the same check but allow empty bodies (the auto-save path needs to
+				// persist work in progress); publish-time validation rejects empty
+				// bodies separately.
+				if (existing.type === 'article' || existing.type === 'newsletter') {
+					const articleContent = contentParsed.data as {
+						bodyMarkdown?: string
+						bodyHtml?: string | null
+					}
+					const bodyMarkdown = articleContent.bodyMarkdown
+					const bodyHtml = articleContent.bodyHtml
+					const isDraft = existing.status === 'draft'
+					if (bodyMarkdown !== undefined || bodyHtml !== undefined) {
+						const guard = evaluateArticleBody(
+							{ body_markdown: bodyMarkdown ?? null, body_html: bodyHtml ?? null },
+							{ source: 'cms.patch', contentId: id, requireBody: !isDraft },
+						)
+						if (!guard.ok) {
+							return json(
+								{ error: 'Article body failed pre-publish validation', errors: guard.errors },
+								422,
+							)
+						}
+					}
+				}
+			}
+
+			const priorSlug = existing.slug
+			const updated = await updateContentItem(ctx.db, id, parsed.data)
+			if (!updated) return json({ error: 'Not found' }, 404)
+			const podcastDispatch =
+				existing.type === 'podcast' ? await maybeDispatchPodcastToFoundry(ctx, id) : null
+
+			// If the slug changed, record the old slug as a redirect (spec §8).
+			if (updated.slug !== priorSlug) {
+				await recordSlugRedirect(ctx.db, priorSlug, id)
+			}
+
+			return json({
+				id,
+				slug: updated.slug,
+				podcastFoundryQueued: Boolean(podcastDispatch),
+				podcastFoundryCorrelationId: podcastDispatch?.correlationId ?? null,
+			})
+		},
+
+		async action(ctx) {
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			const url = new URL(ctx.request.url)
+			const action = url.searchParams.get('action')
+			const existing = await getContentItem(ctx.db, id)
+			if (!existing) return json({ error: 'Not found' }, 404)
+
+			// Map the action verb to a capability, then gate with the ownership
+			// predicate (contributor/producer scoped; owner/senior_editor/editor full).
+			const contentAction = mapActionToCapability(action, existing.type)
+			const denied = await requireContentAction(ctx, contentAction, existing.author_id)
+			if (denied) return denied
+
+			if (action === 'schedule') {
+				const parsed = ScheduleSchema.safeParse(await readJson(ctx))
+				if (!parsed.success) {
+					return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+				}
+
+				let publishAtSeconds: number | null = null
+				const publishTimeZone =
+					parsed.data.timezone || resolved.publishTimezone || PUBLISH_TIMEZONE_FALLBACK
+				if (!isValidTimeZone(publishTimeZone)) {
+					return json({ error: 'Invalid timezone' }, 400)
+				}
+
+				if (parsed.data.publishAtLocal) {
+					publishAtSeconds = parseLocalDateTimeInZoneToUnixSeconds(
+						parsed.data.publishAtLocal,
+						publishTimeZone,
+					)
+					if (!Number.isFinite(publishAtSeconds)) {
+						return json({ error: `Invalid publishAtLocal for ${publishTimeZone} timezone` }, 400)
+					}
+				} else if (parsed.data.publishAt) {
+					const publishAt = Date.parse(parsed.data.publishAt)
+					if (!Number.isFinite(publishAt)) return json({ error: 'Invalid publishAt' }, 400)
+					publishAtSeconds = Math.floor(publishAt / 1000)
+				}
+
+				if (!Number.isFinite(publishAtSeconds)) {
+					return json({ error: 'Missing publish time' }, 400)
+				}
+
+				await scheduleContent(ctx.db, id, publishAtSeconds as number, publishTimeZone)
+
+				// Fire content.scheduled webhook.
+				await fireWebhook(ctx, 'content.scheduled', {
+					id,
+					type: existing.type,
+					title: existing.title,
+					publishAt: publishAtSeconds,
+				})
+
+				return json({ status: 'scheduled' })
+			}
+
+			if (action === 'publish') {
+				const now = Math.floor(Date.now() / 1000)
+				const wasDraft = existing.status === 'draft'
+				let podcastDispatch: DispatchResult | null = null
+				if (existing.type === 'podcast') {
+					try {
+						podcastDispatch = await maybeDispatchPodcastToFoundry(ctx, id)
+					} catch (error) {
+						console.error('Podcast Foundry dispatch failed before publish', error)
+						return json({ error: 'Foundry dispatch failed' }, 502)
+					}
+				}
+				if (publishReadiness) {
+					let readiness: PublishReadinessOutcome
+					try {
+						readiness = await publishReadiness({
+							ctx,
+							contentId: id,
+							type: existing.type,
+							status: existing.status,
+						})
+					} catch (err) {
+						console.error('[cms] publishReadiness failed', err)
+						return json({ error: 'Publish readiness check failed' }, 503)
+					}
+					if (!readiness.ready) {
+						return json(
+							{
+								error: 'Content is not ready to publish',
+								state: readiness.state,
+								blockers: readiness.blockers ?? [],
+								message: readiness.message,
+								etaLabel: readiness.etaLabel,
+								checkedAt: readiness.checkedAt,
+							},
+							readiness.status ?? 409,
+						)
+					}
+				}
+				const guard = await evaluateContentBodyForPublish(ctx.db, id, 'cms.publish')
+				if (guard && !guard.ok) {
+					return json(
+						{
+							error: 'Article body failed pre-publish validation',
+							source: 'cms.publish',
+							errors: guard.errors,
+						},
+						422,
+					)
+				}
+				await publishContent(ctx.db, id, now)
+				await createRevision(ctx.db, id, ctx.userId || null)
+
+				// Write first-party activity log row (cms_activity_log, P5 Task 3).
+				// Wrapped so a logging failure never breaks the publish response.
+				try {
+					await logActivity(ctx.db, {
+						workspaceId: activeWorkspaceId,
+						userId: ctx.userId ?? null,
+						action: 'published',
+						targetId: id,
+						targetTitle: existing.title,
+						type: existing.type,
+					})
+				} catch (err) {
+					console.error('logActivity failed after publish', err)
+				}
+
+				let takeawaysQueued = false
+				if (wasDraft && existing.type === 'article' && dispatchTakeaways) {
+					try {
+						const result = await dispatchTakeaways({ ctx, contentId: id, force: false })
+						takeawaysQueued = result.queued
+					} catch (error) {
+						console.error('Article takeaway dispatch failed', error)
+					}
+				}
+
+				let faqQueued = false
+				if (wasDraft && existing.type === 'article' && dispatchFaq) {
+					try {
+						const result = await dispatchFaq({ ctx, contentId: id, force: false })
+						faqQueued = result.queued
+					} catch (error) {
+						console.error('Article FAQ dispatch failed', error)
+					}
+				}
+
+				// Fire content.published webhook.
+				await fireWebhook(ctx, 'content.published', {
+					id,
+					type: existing.type,
+					title: existing.title,
+				})
+
+				return json({
+					status: 'published',
+					takeawaysQueued,
+					faqQueued,
+					podcastFoundryQueued: Boolean(podcastDispatch),
+					podcastFoundryCorrelationId: podcastDispatch?.correlationId ?? null,
+				})
+			}
+
+			if (action === 'regenerate-takeaways') {
+				if (existing.type !== 'article') return json({ error: 'Invalid content type' }, 400)
+				if (!dispatchTakeaways) {
+					return json({ error: 'Takeaways generation is not configured' }, 501)
+				}
+				try {
+					const result = await dispatchTakeaways({ ctx, contentId: id, force: true })
+					if (!result.queued) {
+						return json({ status: 'skipped', reason: result.reason || 'not queued' }, 409)
+					}
+					return json({ status: 'queued', correlationId: result.correlationId ?? null }, 202)
+				} catch (error) {
+					console.error('Article takeaway regeneration failed', error)
+					return json({ error: 'Foundry dispatch failed' }, 502)
+				}
+			}
+
+			if (action === 'regenerate-faq') {
+				if (existing.type !== 'article') return json({ error: 'Invalid content type' }, 400)
+				if (!dispatchFaq) {
+					return json({ error: 'FAQ generation is not configured' }, 501)
+				}
+				try {
+					const result = await dispatchFaq({ ctx, contentId: id, force: true })
+					if (!result.queued) {
+						return json({ status: 'skipped', reason: result.reason || 'not queued' }, 409)
+					}
+					return json({ status: 'queued', correlationId: result.correlationId ?? null }, 202)
+				} catch (error) {
+					console.error('Article FAQ regeneration failed', error)
+					return json({ error: 'FAQ dispatch failed' }, 502)
+				}
+			}
+
+			if (action === 'unpublish') {
+				await unpublishContent(ctx.db, id)
+
+				// Fire content.unpublished webhook.
+				await fireWebhook(ctx, 'content.unpublished', {
+					id,
+					type: existing.type,
+					title: existing.title,
+				})
+
+				return json({ status: 'draft' })
+			}
+
+			if (action === 'archive') {
+				await ctx.db
+					.prepare(
+						"UPDATE content_items SET status = 'archived', updated_at = unixepoch() WHERE id = ?",
+					)
+					.bind(id)
+					.run()
+
+				// Fire content.deleted (archive = soft delete lifecycle) webhook.
+				await fireWebhook(ctx, 'content.deleted', {
+					id,
+					type: existing.type,
+					title: existing.title,
+					reason: 'archived',
+				})
+
+				return json({ status: 'archived' })
+			}
+
+			if (action === 'unschedule') {
+				// publish_tz is NOT NULL (DEFAULT 'Europe/Paris'); reset it to the
+				// default rather than nulling it (a NULL violates the constraint).
+				await ctx.db
+					.prepare(
+						"UPDATE content_items SET status = 'draft', publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch() WHERE id = ?",
+					)
+					.bind(id)
+					.run()
+				return json({ status: 'draft' })
+			}
+
+			if (action === 'duplicate') {
+				const result = await duplicateContentItem(ctx.db, id)
+				if (!result) return json({ error: 'Not found' }, 404)
+
+				// Fire content.duplicated webhook.
+				await fireWebhook(ctx, 'content.duplicated', {
+					id: result.id,
+					slug: result.slug,
+					sourceId: id,
+					type: existing.type,
+				})
+
+				return json({ id: result.id, slug: result.slug }, 201)
+			}
+
+			if (action === 'set-status') {
+				const parsed = SetStatusSchema.safeParse(await readJson(ctx))
+				if (!parsed.success) {
+					return json(
+						{
+							error: 'Invalid request — status must be "draft" or "review"',
+							details: parsed.error.flatten(),
+						},
+						400,
+					)
+				}
+				const { status } = parsed.data
+				// set-status only ever moves to draft/review (never scheduled), so it is
+				// always a transition OUT of any scheduled state. Clear the stale
+				// publish_at so a de-scheduled item doesn't carry a phantom publish time.
+				// publish_tz is NOT NULL (DEFAULT 'Europe/Paris'), so it is reset to the
+				// default rather than nulled.
+				await ctx.db
+					.prepare(
+						"UPDATE content_items SET status = ?, publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch() WHERE id = ?",
+					)
+					.bind(status, id)
+					.run()
+
+				// Fire content.review when submitted for review.
+				if (status === 'review') {
+					await fireWebhook(ctx, 'content.review', {
+						id,
+						type: existing.type,
+						title: existing.title,
+					})
+				}
+
+				return json({ status })
+			}
+
+			if (action === 'snapshot') {
+				const revision = await createRevisionWithDelta(ctx.db, id, {
+					createdBy: ctx.userId ?? null,
+					tag: 'autosave',
+				})
+				if (!revision) return json({ error: 'Not found' }, 404)
+				return json({ status: 'snapshot', revisionId: revision.id })
+			}
+
+			if (action === 'dispatch-to-foundry') {
+				// Media-type guard: only video and podcast can be dispatched.
+				if (existing.type !== 'video' && existing.type !== 'podcast') {
+					return json(
+						{
+							error: 'dispatch-to-foundry is only valid for video and podcast content types',
+						},
+						400,
+					)
+				}
+				// Hook-presence guard (mirrors the dispatchTakeaways 501 pattern).
+				if (!resolved.hooks.foundryVideo) {
+					return json({ error: 'Foundry video dispatch is not configured' }, 501)
+				}
+				if (existing.type === 'podcast') {
+					const row = await ctx.db
+						.prepare(
+							`SELECT processing_trigger_token
+							FROM podcast_content
+							WHERE content_id = ?
+							LIMIT 1`,
+						)
+						.bind(id)
+						.first<{ processing_trigger_token: string | null }>()
+					const existingToken = row?.processing_trigger_token?.trim() ?? ''
+					if (existingToken) {
+						return json(
+							{
+								status: 'queued',
+								correlationId: null,
+								triggerToken: existingToken,
+								skipped: true,
+							},
+							202,
+						)
+					}
+				}
+				try {
+					const result = await dispatchToFoundry(ctx.db, id, resolved.hooks.foundryVideo)
+					return json(
+						{
+							status: 'queued',
+							correlationId: result.correlationId,
+							triggerToken: result.triggerToken,
+						},
+						202,
+					)
+				} catch (error) {
+					console.error('Foundry dispatch failed', error)
+					return json({ error: 'Foundry dispatch failed' }, 502)
+				}
+			}
+
+			if (action === 'trash') {
+				await softDeleteContent(ctx.db, id)
+
+				// Fire content.deleted (trash) webhook.
+				await fireWebhook(ctx, 'content.deleted', {
+					id,
+					type: existing.type,
+					title: existing.title,
+					reason: 'trashed',
+				})
+
+				return json({ status: 'trashed' })
+			}
+
+			return json({ error: 'Unknown action' }, 400)
+		},
+
+		async foundryCallback(ctx) {
+			// HMAC-guarded machine callback — NOT behind requirePublisher.
+			// The HMAC secret is read from ctx.env (Secrets Store binding on the
+			// Workers side; `env.FOUNDRY_HMAC_SECRET`). Never a value in code/D1.
+			const hmacSecret =
+				typeof ctx.env?.FOUNDRY_HMAC_SECRET === 'string' ? ctx.env.FOUNDRY_HMAC_SECRET : null
+
+			if (!hmacSecret) {
+				// No secret configured — refuse with 500 (misconfiguration).
+				return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+			}
+
+			// Read the raw body text (needed for HMAC verification over the exact bytes).
+			let rawBody: string
+			try {
+				rawBody = await ctx.request.text()
+			} catch {
+				return json({ error: 'Failed to read request body' }, 400)
+			}
+
+			const signature = ctx.request.headers.get('X-Foundry-Signature') ?? ''
+			const valid = await verifyHmac(hmacSecret, rawBody, signature)
+			if (!valid) {
+				return json({ error: 'Invalid signature' }, 401)
+			}
+
+			let payload: Record<string, unknown>
+			try {
+				payload = JSON.parse(rawBody) as Record<string, unknown>
+			} catch {
+				return json({ error: 'Invalid JSON body' }, 400)
+			}
+
+			const eventId = typeof payload.eventId === 'string' ? payload.eventId : null
+			const eventKind = typeof payload.eventKind === 'string' ? payload.eventKind : null
+			const correlationId = typeof payload.correlationId === 'string' ? payload.correlationId : null
+			const triggerToken = typeof payload.triggerToken === 'string' ? payload.triggerToken : null
+			const nextState = typeof payload.nextState === 'string' ? payload.nextState : null
+			const errorMsg = typeof payload.error === 'string' ? payload.error : null
+			const transcript = typeof payload.transcript === 'string' ? payload.transcript : null
+			const durationSeconds =
+				typeof payload.durationSeconds === 'number'
+					? payload.durationSeconds
+					: typeof payload.duration_seconds === 'number'
+						? payload.duration_seconds
+						: null
+			const description =
+				typeof payload.description === 'string'
+					? payload.description
+					: typeof payload.summary === 'string'
+						? payload.summary
+						: null
+			const excerpt =
+				typeof payload.excerpt === 'string'
+					? payload.excerpt
+					: typeof payload.summary === 'string'
+						? payload.summary
+						: null
+
+			if (!eventId || !eventKind || !correlationId || !triggerToken || !nextState) {
+				return json({ error: 'Missing required callback fields' }, 400)
+			}
+
+			const ok = await applyFoundryCallback(ctx.db, {
+				eventId,
+				eventKind,
+				correlationId,
+				triggerToken,
+				nextState: nextState as ProcessingState,
+				error: errorMsg,
+				transcript,
+				durationSeconds,
+				description,
+				excerpt,
+			})
+
+			// Fire video.processed / video.failed webhook on terminal Foundry states.
+			if (nextState === 'ready') {
+				await fireWebhook(ctx, 'video.processed', { correlationId, eventId, eventKind })
+			} else if (nextState === 'failed') {
+				await fireWebhook(ctx, 'video.failed', {
+					correlationId,
+					eventId,
+					eventKind,
+					error: errorMsg,
+				})
+			}
+
+			return json({ ok })
+		},
+
+		async seoScore(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			const item = await getContentItem(ctx.db, id)
+			if (!item) return json({ error: 'Not found' }, 404)
+
+			// Read the persisted body markdown for article / newsletter types.
+			let persistedBodyMarkdown: string | null = null
+			if (item.type === 'article' || item.type === 'newsletter') {
+				const row = await ctx.db
+					.prepare('SELECT body_markdown FROM article_content WHERE content_id = ? LIMIT 1')
+					.bind(id)
+					.first<{ body_markdown: string | null }>()
+				persistedBodyMarkdown = row?.body_markdown ?? null
+			}
+
+			// Read the persisted focus keyword (migration 0004 column).
+			const focusRow = await ctx.db
+				.prepare('SELECT seo_focus_keyword FROM content_items WHERE id = ? LIMIT 1')
+				.bind(id)
+				.first<{ seo_focus_keyword: string | null }>()
+			const persistedFocusKeyword = focusRow?.seo_focus_keyword ?? null
+
+			// Parse optional override fields from the request body.
+			const rawBody = (await readJson(ctx)) as Record<string, unknown> | null
+			const overrides = rawBody && typeof rawBody === 'object' ? rawBody : {}
+
+			const titleOverride = typeof overrides.title === 'string' ? overrides.title : undefined
+			const seoTitleOverride =
+				typeof overrides.seoTitle === 'string' ? overrides.seoTitle : undefined
+			const descriptionOverride =
+				typeof overrides.description === 'string' ? overrides.description : undefined
+			const focusKeywordOverride =
+				typeof overrides.focusKeyword === 'string' ? overrides.focusKeyword : undefined
+			const bodyMarkdownOverride =
+				typeof overrides.bodyMarkdown === 'string' ? overrides.bodyMarkdown : undefined
+
+			const input = {
+				title: titleOverride ?? item.title,
+				seoTitle: seoTitleOverride !== undefined ? seoTitleOverride : (item.seo_title ?? undefined),
+				description:
+					descriptionOverride !== undefined ? descriptionOverride : (item.description ?? undefined),
+				focusKeyword:
+					focusKeywordOverride !== undefined
+						? focusKeywordOverride
+						: (persistedFocusKeyword ?? undefined),
+				bodyMarkdown:
+					bodyMarkdownOverride !== undefined
+						? bodyMarkdownOverride
+						: (persistedBodyMarkdown ?? undefined),
+			}
+
+			const result = await resolved.providers.seo.scoreDraft(input)
+			return json({ score: result.score, checks: result.checks })
+		},
+
+		async contributorsList(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			// 404 if the content item doesn't exist.
+			const item = await getContentItem(ctx.db, id)
+			if (!item) return json({ error: 'Not found' }, 404)
+
+			const contributors = await listContributors(ctx.db, id)
+			return json({ contributors })
+		},
+
+		async contributorsReplace(ctx) {
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			// 404 if the content item doesn't exist.
+			const item = await getContentItem(ctx.db, id)
+			if (!item) return json({ error: 'Not found' }, 404)
+
+			// Editing the byline list is a write on the content item.
+			const denied = await requireContentAction(ctx, 'write', item.author_id)
+			if (denied) return denied
+
+			const parsed = ContributorsReplaceSchema.safeParse(await readJson(ctx))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+
+			await setContributors(
+				ctx.db,
+				id,
+				parsed.data.contributors.map((c) => ({
+					// Prod's content_contributors.role is NOT NULL DEFAULT 'cohost'; an
+					// omitted role must resolve to that default, never NULL. The engine
+					// applies the same fallback as the load-bearing guard.
+					authorId: c.authorId,
+					role: c.role ?? 'cohost',
+					position: c.position,
+				})),
+			)
+
+			const contributors = await listContributors(ctx.db, id)
+			return json({ contributors })
+		},
+
+		async revisionsList(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			// 404 if the content item doesn't exist.
+			const item = await getContentItem(ctx.db, id)
+			if (!item) return json({ error: 'Not found' }, 404)
+
+			const revisions = await listRevisions(ctx.db, id)
+			return json({ revisions })
+		},
+
+		async revisionGet(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			const rev = ctx.params.rev
+			if (!rev) return json({ error: 'Missing rev' }, 400)
+
+			const result = await getRevision(ctx.db, id, rev)
+			if (!result) return json({ error: 'Not found' }, 404)
+
+			return json({ summary: result.summary, payload: result.payload })
+		},
+
+		async revisionRestore(ctx) {
+			const idResult = requireId(ctx)
+			if ('error' in idResult) return idResult.error
+			const id = idResult.id
+
+			// Restoring a revision rewrites content fields → a write on the item.
+			const existing = await getContentItem(ctx.db, id)
+			if (!existing) return json({ error: 'Not found' }, 404)
+			const denied = await requireContentAction(ctx, 'write', existing.author_id)
+			if (denied) return denied
+
+			const rev = ctx.params.rev
+			if (!rev) return json({ error: 'Missing rev' }, 400)
+
+			const ok = await restoreRevision(ctx.db, id, rev, { createdBy: ctx.userId ?? null })
+			if (!ok) return json({ error: 'Not found' }, 404)
+
+			return json({ restored: true })
+		},
+	}
+}