@growth-labs/cms 0.5.29 → 0.5.31

package/src/engine/fronts-publish-intent.ts

@@ -0,0 +1,676 @@
+// Canonical Fronts publish intent — the CMS-owned hydration contract a pull
+// consumer needs to build a COMPLETE publish intent from a due or overdue
+// schedule item (packages#500, under the GO-PLANE PULL-PRIMARY spec).
+//
+// The 0026 schedule poll (engine/fronts-publish.ts `listFrontsPublishSchedule`)
+// returns presentation columns only — id, type, slug, title, channel,
+// publish_at, fronts_publish_status. A consumer polling that surface could not
+// build `intent_id = masthead:<content_id>:<version>`, could not know WHERE to
+// publish, and could not resolve the media to attach; the only ways forward were
+// to invent values or take them from an untrusted payload, both forbidden. This
+// module supplies those values from authoritative CMS storage and FAILS LOUDLY
+// when a required one does not exist.
+//
+// The full field/source table, the version semantics, the per-media-type absence
+// rules and the auth byte contract are documented in `packages-docs/cms.md`
+// ("Fronts publish path — canonical intent contract"). The load-bearing points
+// for a reader of this file:
+//
+//   * ALL times are unix epoch SECONDS — the same column and units the legacy
+//     cron predicate uses, so there is no D1 `datetime('now')` TEXT comparison
+//     on `publish_at` and no space-vs-`T` skew trap.
+//   * `version` is `content_items.canonical_version`, advanced by exactly one
+//     seam (updateContentItem) — NOT by a fronts_publish_status marker write and
+//     NOT by polling, so repeated reads are identity-stable while a real
+//     canonical revision does change identity.
+//   * `trigger_token_hash` is `sha256:<hex>` of
+//     `content_items.fronts_publish_trigger_token`. The raw token is secret at
+//     rest exactly like `video_content.processing_trigger_token` (migration
+//     0006) and NEVER leaves this package.
+//   * Absence is explicit per media type: an article needs a body, a video needs
+//     a READY HLS manifest, a podcast needs an audio object; `images` and
+//     `links` are always optionally empty. Anything required and missing is a
+//     `FrontsPublishIntentError`, never an empty default.
+//   * KNOWN GAP, reported not papered over: the wire field is
+//     `podcast_audio_hls`, but the CMS stores only
+//     `podcast_content.audio_r2_key`, a progressive-download R2 object and NOT a
+//     manifest. The ref carries an explicit `kind` discriminator that today
+//     always reads `'r2-object'`, so a consumer can never mistake one for the
+//     other. Real audio HLS is a separate media-pipeline change.
+import type { ContentType, FrontsPublishStatus } from '../schema/types.js'
+import type { D1Database } from './d1.js'
+
+/** The CMS's own name for the record this intent describes. */
+export const FRONTS_PUBLISH_INTENT_SOURCE = 'masthead'
+
+/**
+ * `masthead:<content_id>:<version>`. Stable for as long as the canonical
+ * content is, and different the moment `canonical_version` advances, so a
+ * meaningful revision can never silently reuse a conflicting identity.
+ */
+export function frontsPublishIntentId(contentId: string, version: number): string {
+	return `${FRONTS_PUBLISH_INTENT_SOURCE}:${contentId}:${version}`
+}
+
+/** Every way a due item can fail to form a complete, honest intent. */
+export type FrontsPublishIntentErrorCode =
+	| 'missing_publish_at'
+	| 'invalid_canonical_version'
+	| 'missing_channel_targets'
+	| 'invalid_channel_targets'
+	| 'missing_trigger_token'
+	| 'missing_article_body'
+	| 'video_media_not_ready'
+	| 'missing_podcast_audio'
+
+/**
+ * A due item whose canonical data cannot produce a complete intent. Thrown by
+ * the single-item hydration; collected (never swallowed) by the batch one.
+ */
+export class FrontsPublishIntentError extends Error {
+	readonly code: FrontsPublishIntentErrorCode
+	readonly contentId: string
+	constructor(code: FrontsPublishIntentErrorCode, contentId: string, detail?: string) {
+		super(`fronts publish intent ${code} for content ${contentId}${detail ? `: ${detail}` : ''}`)
+		this.name = 'FrontsPublishIntentError'
+		this.code = code
+		this.contentId = contentId
+	}
+}
+
+// --- wire shape ------------------------------------------------------------
+
+export interface FrontsPublishArticleRef {
+	/** Absolute when a site base/canonical URL is known, else a site-relative path. */
+	url: string
+	slug: string
+	word_count: number | null
+}
+
+export interface FrontsPublishImageRef {
+	id: string
+	role: 'hero' | 'social' | 'thumbnail'
+	url: string
+	width: number | null
+	height: number | null
+}
+
+export interface FrontsPublishVideoHlsRef {
+	kind: 'hls-manifest'
+	url: string
+	poster_url: string | null
+	duration_seconds: number | null
+}
+
+export interface FrontsPublishPodcastAudioRef {
+	/**
+	 * `'r2-object'` — a progressive-download R2 audio object
+	 * (podcast_content.audio_r2_key), which is what the CMS actually stores.
+	 * `'hls-manifest'` is reserved for when an audio HLS pipeline exists. Always
+	 * check this before treating `url` as a manifest.
+	 */
+	kind: 'r2-object' | 'hls-manifest'
+	url: string
+	duration_seconds: number | null
+}
+
+export interface FrontsPublishLinkRef {
+	rel: 'canonical' | 'public'
+	url: string
+}
+
+export interface FrontsPublishContentRefs {
+	article: FrontsPublishArticleRef | null
+	/** `[]` is valid — the item simply has no hero/social/thumbnail asset. */
+	images: FrontsPublishImageRef[]
+	video_hls: FrontsPublishVideoHlsRef | null
+	podcast_audio_hls: FrontsPublishPodcastAudioRef | null
+	/** `[]` is valid. */
+	links: FrontsPublishLinkRef[]
+}
+
+/**
+ * One due/overdue item's complete canonical publish intent. Contains NO secret:
+ * `trigger_token_hash` is a digest and the raw token never leaves D1.
+ */
+export interface FrontsPublishIntent {
+	intent_id: string
+	content_id: string
+	version: number
+	type: ContentType
+	slug: string
+	title: string
+	/** The single editorial Fronts channel slug — NOT a publish target. */
+	channel: string | null
+	channel_targets: string[]
+	/** Unix epoch SECONDS. Equals content_items.publish_at. */
+	deadline: number
+	/**
+	 * Unix epoch SECONDS. Equals `deadline` in this increment: the CMS declares no
+	 * pre-roll lead of its own rather than inventing one. A host-configurable lead
+	 * is deliberately deferred — see packages-docs/cms.md.
+	 */
+	trigger_at: number
+	content_refs: FrontsPublishContentRefs
+	/** `sha256:<64 lowercase hex>`. Never the raw token. */
+	trigger_token_hash: string
+	/** `deadline <= now` — the consumer is late on this one. */
+	overdue: boolean
+	fronts_publish_status: FrontsPublishStatus | null
+}
+
+// --- trigger token ---------------------------------------------------------
+
+/** SHA-256 hex digest via Web Crypto (never node:crypto). */
+async function sha256Hex(input: string): Promise<string> {
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
+	return Array.from(new Uint8Array(digest))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+}
+
+/** The `sha256:` prefix every exposed CMS trigger-token digest carries. */
+export const FRONTS_PUBLISH_TRIGGER_TOKEN_HASH_PREFIX = 'sha256:'
+
+/**
+ * The exposed form of a trigger token: `sha256:<hex>`. Same convention
+ * `engine/foundry-dispatch.ts` already uses for `processingTriggerTokenHash`.
+ */
+export async function frontsPublishTriggerTokenHash(rawToken: string): Promise<string> {
+	return `${FRONTS_PUBLISH_TRIGGER_TOKEN_HASH_PREFIX}${await sha256Hex(rawToken)}`
+}
+
+/**
+ * Mint this item's raw publish trigger token if — and only if — it has none.
+ *
+ * Idempotent by compare-and-set, so concurrent callers cannot produce two tokens
+ * and a re-arm never rotates a token out from under an in-flight intent: an
+ * armed item keeps one stable `trigger_token_hash` across every later read.
+ * Called from `scheduleContent`, the single seam an item passes through to
+ * become `scheduled` with a `publish_at`. The raw value is never returned.
+ */
+export async function armFrontsPublishTriggerToken(
+	db: D1Database,
+	contentId: string,
+): Promise<{ minted: boolean }> {
+	const result = await db
+		.prepare(
+			`UPDATE content_items
+			 SET fronts_publish_trigger_token = ?
+			 WHERE id = ? AND fronts_publish_trigger_token IS NULL`,
+		)
+		.bind(crypto.randomUUID(), contentId)
+		.run()
+	// `meta` is a structural Record<string, unknown> on the package's minimal D1
+	// surface, so narrow before comparing (same idiom as fronts-publish.ts).
+	const changes = result.meta?.changes
+	return { minted: typeof changes === 'number' && changes > 0 }
+}
+
+// --- channel targets -------------------------------------------------------
+
+/**
+ * Parse `content_items.fronts_channel_targets`. Returns the target list, or a
+ * loud error code — NEVER a silent `[]`, which would read as a complete intent
+ * with nothing to publish to.
+ */
+type ChannelTargetsFailure = { code: 'missing_channel_targets' | 'invalid_channel_targets' }
+
+/** Single source of truth for what a publishable target list IS — shared by the
+ * stored-value parser and the setter so the two can never diverge. */
+function normalizeChannelTargets(
+	entries: readonly unknown[],
+): { targets: string[] } | ChannelTargetsFailure {
+	const targets: string[] = []
+	for (const entry of entries) {
+		if (typeof entry !== 'string' || entry.trim() === '') {
+			return { code: 'invalid_channel_targets' }
+		}
+		const target = entry.trim()
+		if (!targets.includes(target)) targets.push(target)
+	}
+	if (targets.length === 0) return { code: 'missing_channel_targets' }
+	return { targets }
+}
+
+export function parseFrontsChannelTargets(
+	raw: string | null | undefined,
+): { targets: string[] } | ChannelTargetsFailure {
+	if (raw === null || raw === undefined || raw.trim() === '') {
+		return { code: 'missing_channel_targets' }
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		return { code: 'invalid_channel_targets' }
+	}
+	if (!Array.isArray(parsed)) return { code: 'invalid_channel_targets' }
+	return normalizeChannelTargets(parsed)
+}
+
+/**
+ * Arm an item's publish targets. Rejects an empty or non-string list loudly
+ * instead of storing something that would later hydrate as "complete".
+ */
+export async function setFrontsChannelTargets(
+	db: D1Database,
+	contentId: string,
+	targets: readonly string[],
+): Promise<void> {
+	const normalized = normalizeChannelTargets(targets)
+	if ('code' in normalized) {
+		throw new FrontsPublishIntentError(
+			normalized.code,
+			contentId,
+			'targets must be a non-empty list of non-empty strings',
+		)
+	}
+	await db
+		.prepare('UPDATE content_items SET fronts_channel_targets = ? WHERE id = ?')
+		.bind(JSON.stringify(normalized.targets), contentId)
+		.run()
+}
+
+// --- hydration -------------------------------------------------------------
+
+/** The candidate columns read from `content_items` for one due item. */
+interface IntentCandidateRow {
+	id: string
+	type: ContentType
+	slug: string
+	title: string
+	channel: string | null
+	publish_at: number | null
+	fronts_publish_status: FrontsPublishStatus | null
+	canonical_version: number | null
+	fronts_channel_targets: string | null
+	fronts_publish_trigger_token: string | null
+	canonical_url: string | null
+	hero_image_id: string | null
+	social_image_id: string | null
+}
+
+const CANDIDATE_COLUMNS = `id, type, slug, title, channel, publish_at, fronts_publish_status,
+			 canonical_version, fronts_channel_targets, fronts_publish_trigger_token,
+			 canonical_url, hero_image_id, social_image_id`
+
+export interface HydrateFrontsPublishIntentsOptions {
+	/** Window upper bound, unix epoch seconds. Items due at/before this are considered. */
+	toSeconds: number
+	/** Reference time for `overdue`, unix epoch seconds. Defaults to Date.now(). */
+	nowSeconds?: number
+	/** Hard cap on candidates. Default 200, max 1000 — mirrors the schedule poll. */
+	limit?: number
+	/**
+	 * Resolve an item's public URL (absolute when the host knows its origin, else
+	 * a site-relative path). Injected rather than imported so this engine module
+	 * does not depend on the UI layer.
+	 */
+	resolveContentUrl: (row: { type: ContentType; slug: string }) => string
+	/** Public media host used for media rows with no stored URL. Default 'media.fronts.co'. */
+	mediaPublicDomain?: string
+}
+
+/** One due item that could NOT form a complete intent, with the exact reason. */
+export interface FrontsPublishIntentFailure {
+	content_id: string
+	code: FrontsPublishIntentErrorCode
+	message: string
+}
+
+export interface HydrateFrontsPublishIntentsResult {
+	intents: FrontsPublishIntent[]
+	/**
+	 * Due items that are NOT publishable — never empty-defaulted into `intents`
+	 * and never silently dropped. One bad item does not suppress the others, so a
+	 * single broken record cannot block the whole publish lane.
+	 */
+	incomplete: FrontsPublishIntentFailure[]
+}
+
+/** `?, ?, ?` for an IN clause of `count` bound values. */
+function placeholders(count: number): string {
+	return new Array(count).fill('?').join(', ')
+}
+
+interface ArticleRefRow {
+	content_id: string
+	body_markdown: string | null
+	word_count: number | null
+}
+
+interface VideoRefRow {
+	content_id: string
+	hls_ready: number
+	hls_manifest_url: string | null
+	hls_poster_url: string | null
+	duration_seconds: number | null
+	thumbnail_image_id: string | null
+}
+
+interface PodcastRefRow {
+	content_id: string
+	audio_r2_key: string | null
+	duration_seconds: number | null
+}
+
+interface MediaRow {
+	id: string
+	object_key: string | null
+	public_url: string | null
+	url: string | null
+	width: number | null
+	height: number | null
+}
+
+/** An R2 object key (or already-absolute URL) against the public media host. */
+function objectKeyUrl(key: string, mediaPublicDomain: string): string {
+	if (/^https?:\/\//i.test(key)) return key
+	return `https://${mediaPublicDomain}/${key.replace(/^\/+/, '')}`
+}
+
+/** Resolve a media row to its public URL, or null when it has no usable form. */
+function mediaUrl(row: MediaRow, mediaPublicDomain: string): string | null {
+	const stored = row.public_url?.trim() || row.url?.trim()
+	if (stored) return stored
+	const key = row.object_key?.trim()
+	return key ? objectKeyUrl(key, mediaPublicDomain) : null
+}
+
+/**
+ * Hydrate every due/overdue `scheduled` item into a complete canonical intent.
+ *
+ * Uses the SAME due predicate as `listFrontsPublishSchedule` — overdue items
+ * included (the window's lower bound is deliberately not applied), future items
+ * excluded — so existing window behaviour is preserved exactly. READ ONLY: it
+ * never mutates content, advances `canonical_version`, or mints a token, so
+ * polling cannot churn an intent identity.
+ */
+export async function hydrateFrontsPublishIntents(
+	db: D1Database,
+	options: HydrateFrontsPublishIntentsOptions,
+): Promise<HydrateFrontsPublishIntentsResult> {
+	const now = options.nowSeconds ?? Math.floor(Date.now() / 1_000)
+	const limit = Math.min(Math.max(1, Math.floor(options.limit ?? 200)), 1000)
+	const mediaPublicDomain = options.mediaPublicDomain ?? 'media.fronts.co'
+
+	const candidates = await db
+		.prepare(
+			`SELECT ${CANDIDATE_COLUMNS}
+			 FROM content_items
+			 WHERE status = 'scheduled'
+			   AND publish_at IS NOT NULL
+			   AND publish_at <= ?
+			 ORDER BY publish_at ASC
+			 LIMIT ?`,
+		)
+		.bind(options.toSeconds, limit)
+		.all<IntentCandidateRow>()
+
+	const rows = candidates.results ?? []
+	if (rows.length === 0) return { intents: [], incomplete: [] }
+
+	const refs = await loadContentRefSources(db, rows)
+	const intents: FrontsPublishIntent[] = []
+	const incomplete: FrontsPublishIntentFailure[] = []
+
+	for (const row of rows) {
+		try {
+			intents.push(
+				await buildIntent(row, refs, {
+					now,
+					mediaPublicDomain,
+					resolve: options.resolveContentUrl,
+				}),
+			)
+		} catch (error) {
+			if (error instanceof FrontsPublishIntentError) {
+				// LOUD: an operator can see exactly which due item is unpublishable and why.
+				console.error(`[cms] fronts publish intent incomplete: ${error.message}`)
+				incomplete.push({ content_id: error.contentId, code: error.code, message: error.message })
+				continue
+			}
+			throw error
+		}
+	}
+
+	return { intents, incomplete }
+}
+
+/** Batched per-type + media lookups — a fixed query count, not one per item. */
+async function loadContentRefSources(
+	db: D1Database,
+	rows: readonly IntentCandidateRow[],
+): Promise<{
+	articles: Map<string, ArticleRefRow>
+	videos: Map<string, VideoRefRow>
+	podcasts: Map<string, PodcastRefRow>
+	media: Map<string, MediaRow>
+}> {
+	const bodyBackedIds = rows
+		.filter((r) => r.type === 'article' || r.type === 'newsletter' || r.type === 'page')
+		.map((r) => r.id)
+	const videoIds = rows.filter((r) => r.type === 'video').map((r) => r.id)
+	const podcastIds = rows.filter((r) => r.type === 'podcast').map((r) => r.id)
+
+	const articles = new Map<string, ArticleRefRow>()
+	if (bodyBackedIds.length > 0) {
+		const res = await db
+			.prepare(
+				`SELECT content_id, body_markdown, word_count FROM article_content
+				 WHERE content_id IN (${placeholders(bodyBackedIds.length)})`,
+			)
+			.bind(...bodyBackedIds)
+			.all<ArticleRefRow>()
+		for (const r of res.results ?? []) articles.set(r.content_id, r)
+	}
+
+	const videos = new Map<string, VideoRefRow>()
+	if (videoIds.length > 0) {
+		const res = await db
+			.prepare(
+				`SELECT content_id, hls_ready, hls_manifest_url, hls_poster_url, duration_seconds,
+				        thumbnail_image_id
+				 FROM video_content WHERE content_id IN (${placeholders(videoIds.length)})`,
+			)
+			.bind(...videoIds)
+			.all<VideoRefRow>()
+		for (const r of res.results ?? []) videos.set(r.content_id, r)
+	}
+
+	const podcasts = new Map<string, PodcastRefRow>()
+	if (podcastIds.length > 0) {
+		const res = await db
+			.prepare(
+				`SELECT content_id, audio_r2_key, duration_seconds FROM podcast_content
+				 WHERE content_id IN (${placeholders(podcastIds.length)})`,
+			)
+			.bind(...podcastIds)
+			.all<PodcastRefRow>()
+		for (const r of res.results ?? []) podcasts.set(r.content_id, r)
+	}
+
+	const mediaIds: string[] = []
+	const pushMediaId = (id: string | null | undefined) => {
+		const trimmed = id?.trim()
+		if (trimmed && !mediaIds.includes(trimmed)) mediaIds.push(trimmed)
+	}
+	for (const row of rows) {
+		pushMediaId(row.hero_image_id)
+		pushMediaId(row.social_image_id)
+	}
+	for (const video of videos.values()) pushMediaId(video.thumbnail_image_id)
+
+	const media = new Map<string, MediaRow>()
+	if (mediaIds.length > 0) {
+		const res = await db
+			.prepare(
+				`SELECT id, object_key, public_url, url, width, height FROM media_assets
+				 WHERE id IN (${placeholders(mediaIds.length)})`,
+			)
+			.bind(...mediaIds)
+			.all<MediaRow>()
+		for (const r of res.results ?? []) media.set(r.id, r)
+	}
+
+	return { articles, videos, podcasts, media }
+}
+
+/** Build one intent, throwing FrontsPublishIntentError on any missing required value. */
+async function buildIntent(
+	row: IntentCandidateRow,
+	refs: Awaited<ReturnType<typeof loadContentRefSources>>,
+	ctx: {
+		now: number
+		mediaPublicDomain: string
+		resolve: (r: { type: ContentType; slug: string }) => string
+	},
+): Promise<FrontsPublishIntent> {
+	if (row.publish_at === null || !Number.isFinite(row.publish_at)) {
+		throw new FrontsPublishIntentError('missing_publish_at', row.id)
+	}
+	const version = row.canonical_version
+	if (version === null || !Number.isInteger(version) || version < 1) {
+		throw new FrontsPublishIntentError(
+			'invalid_canonical_version',
+			row.id,
+			`canonical_version must be a positive integer, got ${String(version)}`,
+		)
+	}
+
+	const targets = parseFrontsChannelTargets(row.fronts_channel_targets)
+	if ('code' in targets) {
+		throw new FrontsPublishIntentError(
+			targets.code,
+			row.id,
+			'content_items.fronts_channel_targets must be a JSON array of target slugs',
+		)
+	}
+
+	const rawToken = row.fronts_publish_trigger_token?.trim()
+	if (!rawToken) {
+		throw new FrontsPublishIntentError(
+			'missing_trigger_token',
+			row.id,
+			'item was never armed for the Fronts publish path (no fronts_publish_trigger_token)',
+		)
+	}
+
+	const deadline = Math.floor(row.publish_at)
+	return {
+		intent_id: frontsPublishIntentId(row.id, version),
+		content_id: row.id,
+		version,
+		type: row.type,
+		slug: row.slug,
+		title: row.title,
+		channel: row.channel,
+		channel_targets: targets.targets,
+		deadline,
+		trigger_at: deadline,
+		content_refs: buildContentRefs(row, refs, ctx),
+		trigger_token_hash: await frontsPublishTriggerTokenHash(rawToken),
+		overdue: deadline <= ctx.now,
+		fronts_publish_status: row.fronts_publish_status,
+	}
+}
+
+/** Per-type content refs, applying the absence rules in the module header. */
+function buildContentRefs(
+	row: IntentCandidateRow,
+	refs: Awaited<ReturnType<typeof loadContentRefSources>>,
+	ctx: {
+		mediaPublicDomain: string
+		resolve: (r: { type: ContentType; slug: string }) => string
+	},
+): FrontsPublishContentRefs {
+	const publicUrl = ctx.resolve({ type: row.type, slug: row.slug })
+	const canonicalUrl = row.canonical_url?.trim() || null
+
+	// --- article: required for body-backed types, validly absent otherwise.
+	let article: FrontsPublishArticleRef | null = null
+	const bodyBacked = row.type === 'article' || row.type === 'newsletter' || row.type === 'page'
+	if (bodyBacked) {
+		const found = refs.articles.get(row.id)
+		if (!found?.body_markdown || found.body_markdown.trim() === '') {
+			throw new FrontsPublishIntentError(
+				'missing_article_body',
+				row.id,
+				`a ${row.type} intent requires a non-empty article_content.body_markdown`,
+			)
+		}
+		article = {
+			url: canonicalUrl ?? publicUrl,
+			slug: row.slug,
+			word_count: found.word_count ?? null,
+		}
+	}
+
+	// --- video_hls: required for video, and only when genuinely ready.
+	let videoHls: FrontsPublishVideoHlsRef | null = null
+	if (row.type === 'video') {
+		const found = refs.videos.get(row.id)
+		const manifest = found?.hls_manifest_url?.trim()
+		if (!found || found.hls_ready !== 1 || !manifest) {
+			throw new FrontsPublishIntentError(
+				'video_media_not_ready',
+				row.id,
+				'a video intent requires video_content.hls_ready = 1 and a non-empty hls_manifest_url',
+			)
+		}
+		videoHls = {
+			kind: 'hls-manifest',
+			url: manifest,
+			poster_url: found.hls_poster_url?.trim() || null,
+			duration_seconds: found.duration_seconds ?? null,
+		}
+	}
+
+	// --- podcast_audio_hls: required for podcast. See the module header for why
+	//     `kind` is 'r2-object' today rather than a manifest.
+	let podcastAudio: FrontsPublishPodcastAudioRef | null = null
+	if (row.type === 'podcast') {
+		const found = refs.podcasts.get(row.id)
+		const key = found?.audio_r2_key?.trim()
+		if (!found || !key) {
+			throw new FrontsPublishIntentError(
+				'missing_podcast_audio',
+				row.id,
+				'a podcast intent requires a non-empty podcast_content.audio_r2_key',
+			)
+		}
+		podcastAudio = {
+			kind: 'r2-object',
+			url: objectKeyUrl(key, ctx.mediaPublicDomain),
+			duration_seconds: found.duration_seconds ?? null,
+		}
+	}
+
+	// --- images: always optional. [] means the item has no assets.
+	const images: FrontsPublishImageRef[] = []
+	const pushImage = (id: string | null | undefined, role: FrontsPublishImageRef['role']) => {
+		const assetId = id?.trim()
+		if (!assetId) return
+		const asset = refs.media.get(assetId)
+		if (!asset) return
+		const url = mediaUrl(asset, ctx.mediaPublicDomain)
+		if (!url) return
+		images.push({
+			id: assetId,
+			role,
+			url,
+			width: asset.width ?? null,
+			height: asset.height ?? null,
+		})
+	}
+	pushImage(row.hero_image_id, 'hero')
+	pushImage(row.social_image_id, 'social')
+	pushImage(refs.videos.get(row.id)?.thumbnail_image_id, 'thumbnail')
+
+	// --- links: always optional.
+	const links: FrontsPublishLinkRef[] = [{ rel: 'public', url: publicUrl }]
+	if (canonicalUrl) links.push({ rel: 'canonical', url: canonicalUrl })
+
+	return { article, images, video_hls: videoHls, podcast_audio_hls: podcastAudio, links }
+}