@growth-labs/cms 0.6.5 → 0.6.7

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

@@ -19,8 +19,9 @@
 //   * 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
+//   * `version` is `content_items.canonical_version`, advanced by canonical edits
+//     and actual delete/restore/archive transitions — NOT by scheduling or 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
@@ -28,7 +29,7 @@
 //     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
+//     a READY HLS manifest, a podcast needs audio and its transcript; `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
@@ -39,6 +40,12 @@
 //     other. Real audio HLS is a separate media-pipeline change.
 import type { ContentType, FrontsPublishStatus } from '../schema/types.js'
 import type { D1Database } from './d1.js'
+import {
+	frontsPodcastSourceGeneration,
+	type PodcastPublishBlockerCode,
+	podcastPublishBlocker,
+	validPodcastSourceUrl,
+} from './podcast-source.js'
 
 /** The CMS's own name for the record this intent describes. */
 export const FRONTS_PUBLISH_INTENT_SOURCE = 'masthead'
@@ -62,6 +69,7 @@ export type FrontsPublishIntentErrorCode =
 	| 'missing_article_body'
 	| 'video_media_not_ready'
 	| 'missing_podcast_audio'
+	| PodcastPublishBlockerCode
 
 /**
  * A due item whose canonical data cannot produce a complete intent. Thrown by
@@ -122,12 +130,16 @@ export interface FrontsPublishPodcastAudioRef {
  * dispatch time" pattern `video_content.processing_source_url` already uses.
  * `kind` is always `'https'` today: a single literal, not an open enum,
  * because there is exactly one supported source kind. Present only while the
- * podcast has a source but no audio yet; once `podcast_audio_hls` exists this
- * is null, so a consumer never sees both at once.
+ * podcast is incomplete. An existing audio object with a missing transcript
+ * still needs production; it is not a publishable audio reference yet.
  */
 export interface FrontsPublishPodcastSourceRef {
 	kind: 'https'
 	url: string
+	/** Immutable media identity; rescheduling alone does not change it. */
+	generation: string
+	/** Positive finite duration measured for the current captured source. */
+	duration_seconds: number
 }
 
 export interface FrontsPublishLinkRef {
@@ -141,7 +153,7 @@ export interface FrontsPublishContentRefs {
 	images: FrontsPublishImageRef[]
 	video_hls: FrontsPublishVideoHlsRef | null
 	podcast_audio_hls: FrontsPublishPodcastAudioRef | null
-	/** Null once podcast_audio_hls exists, or if no source was ever captured. */
+	/** Present only while media is incomplete and a valid source was captured. */
 	podcast_source: FrontsPublishPodcastSourceRef | null
 	/** `[]` is valid. */
 	links: FrontsPublishLinkRef[]
@@ -328,6 +340,8 @@ export interface HydrateFrontsPublishIntentsOptions {
 	resolveContentUrl: (row: { type: ContentType; slug: string }) => string
 	/** Public media host used for media rows with no stored URL. Default 'media.fronts.co'. */
 	mediaPublicDomain?: string
+	/** False keeps source-only readiness failures visible without requesting production. */
+	podcastSourceProductionEnabled?: boolean
 }
 
 /** One due item that could NOT form a complete intent, with the exact reason. */
@@ -357,6 +371,13 @@ export interface HydrateFrontsPublishIntentsResult {
 	incomplete: FrontsPublishIntentFailure[]
 }
 
+export class FrontsScheduleOverflowError extends Error {
+	constructor(readonly limit: number) {
+		super(`Scheduled content exceeds the bounded ${limit}-item response.`)
+		this.name = 'FrontsScheduleOverflowError'
+	}
+}
+
 /** `?, ?, ?` for an IN clause of `count` bound values. */
 function placeholders(count: number): string {
 	return new Array(count).fill('?').join(', ')
@@ -379,10 +400,12 @@ interface VideoRefRow {
 
 interface PodcastRefRow {
 	content_id: string
+	transcript: string | null
 	audio_r2_key: string | null
 	duration_seconds: number | null
 	processing_source_url: string | null
 	processing_source_kind: string | null
+	processing_trigger_token: string | null
 }
 
 interface MediaRow {
@@ -430,15 +453,17 @@ export async function hydrateFrontsPublishIntents(
 			`SELECT ${CANDIDATE_COLUMNS}
 			 FROM content_items
 			 WHERE status = 'scheduled'
+			   AND deleted_at IS NULL
 			   AND publish_at IS NOT NULL
 			   AND publish_at <= ?
 			 ORDER BY publish_at ASC
 			 LIMIT ?`,
 		)
-		.bind(options.toSeconds, limit)
+		.bind(options.toSeconds, limit + 1)
 		.all<IntentCandidateRow>()
 
 	const rows = candidates.results ?? []
+	if (rows.length > limit) throw new FrontsScheduleOverflowError(limit)
 	if (rows.length === 0) return { intents: [], incomplete: [] }
 
 	const refs = await loadContentRefSources(db, rows)
@@ -452,10 +477,11 @@ export async function hydrateFrontsPublishIntents(
 				mediaPublicDomain,
 				resolve: options.resolveContentUrl,
 			})
-			intents.push(intent)
-			// The one dual-signal case (M2-B2): a podcast with a source but no
-			// audio yet is a real intents[] entry AND an incomplete[] entry at
-			// once, not either/or -- see buildContentRefs's module comment.
+			if (options.podcastSourceProductionEnabled !== false || !intent.content_refs.podcast_source) {
+				intents.push(intent)
+			}
+			// A podcast with a source but incomplete media is visible to the
+			// production consumer and remains explicitly unpublishable.
 			if (dualSignal) incomplete.push(dualSignal)
 		} catch (error) {
 			if (error instanceof FrontsPublishIntentError) {
@@ -521,7 +547,7 @@ async function loadContentRefSources(
 	if (podcastIds.length > 0) {
 		const res = await db
 			.prepare(
-				`SELECT content_id, audio_r2_key, duration_seconds, processing_source_url, processing_source_kind FROM podcast_content
+				`SELECT content_id, transcript, audio_r2_key, duration_seconds, processing_source_url, processing_source_kind, processing_trigger_token FROM podcast_content
 				 WHERE content_id IN (${placeholders(podcastIds.length)})`,
 			)
 			.bind(...podcastIds)
@@ -596,7 +622,7 @@ async function buildIntent(
 	}
 
 	const deadline = Math.floor(row.publish_at)
-	const { refs: contentRefs, incomplete } = buildContentRefs(row, refs, ctx)
+	const { refs: contentRefs, incomplete } = await buildContentRefs(row, refs, ctx)
 	return {
 		intent: {
 			intent_id: frontsPublishIntentId(row.id, version),
@@ -621,21 +647,21 @@ async function buildIntent(
 /**
  * Per-type content refs, applying the absence rules in the module header.
  * Returns an `incomplete` note alongside a normally-complete refs object for
- * exactly one dual-signal case (M2-B2): a podcast with a processing source
- * captured but no audio yet. That item is genuinely not publishable (still
+ * a podcast with a processing source and incomplete audio/transcript evidence.
+ * That item is not publishable (still
  * worth an incomplete[] entry, same code as before) but is also not nothing
  * -- a pull consumer needs `podcast_source` to start production, so this
  * function returns it rather than throwing it away with the rest of the
  * intent the way every OTHER missing-required-value case still does.
  */
-function buildContentRefs(
+async function buildContentRefs(
 	row: IntentCandidateRow,
 	refs: Awaited<ReturnType<typeof loadContentRefSources>>,
 	ctx: {
 		mediaPublicDomain: string
 		resolve: (r: { type: ContentType; slug: string }) => string
 	},
-): { refs: FrontsPublishContentRefs; incomplete: FrontsPublishIntentFailure | null } {
+): Promise<{ refs: FrontsPublishContentRefs; incomplete: FrontsPublishIntentFailure | null }> {
 	const publicUrl = ctx.resolve({ type: row.type, slug: row.slug })
 	const canonicalUrl = row.canonical_url?.trim() || null
 
@@ -698,26 +724,52 @@ function buildContentRefs(
 	if (row.type === 'podcast') {
 		const found = refs.podcasts.get(row.id)
 		const key = found?.audio_r2_key?.trim()
-		if (found && key) {
+		const blocker = podcastPublishBlocker(found)
+		if (found && key && !blocker) {
 			podcastAudio = {
 				kind: 'r2-object',
 				url: objectKeyUrl(key, ctx.mediaPublicDomain),
 				duration_seconds: found.duration_seconds ?? null,
 			}
 		} else {
-			const message = 'a podcast intent requires a non-empty podcast_content.audio_r2_key'
-			const sourceUrl = found?.processing_source_url?.trim()
-			const sourceKind = found?.processing_source_kind?.trim()
-			if (sourceUrl && sourceKind === 'https') {
-				podcastSource = { kind: 'https', url: sourceUrl }
+			const failure = blocker ?? {
+				code: 'missing_podcast_audio' as const,
+				message: 'Podcast audio is not ready.',
+			}
+			const sourceUrl = found?.processing_source_url
+			if (found && validPodcastSourceUrl(sourceUrl) && found.processing_source_kind === 'https') {
+				if (
+					typeof found.duration_seconds !== 'number' ||
+					!Number.isFinite(found.duration_seconds) ||
+					found.duration_seconds <= 0
+				) {
+					throw new FrontsPublishIntentError(
+						'podcast_source_duration_unavailable',
+						row.id,
+						'Podcast source duration is not verified.',
+					)
+				}
+				podcastSource = {
+					kind: 'https',
+					url: sourceUrl,
+					duration_seconds: found.duration_seconds,
+					generation: await frontsPodcastSourceGeneration({
+						content_id: row.id,
+						slug: row.slug,
+						canonical_version: row.canonical_version as number,
+						processing_source_url: found.processing_source_url,
+						processing_source_kind: found.processing_source_kind,
+						processing_trigger_token: found.processing_trigger_token,
+					}),
+				}
 				incomplete = {
 					content_id: row.id,
-					code: 'missing_podcast_audio',
-					message,
+					code: failure.code,
+					message: failure.message,
 					publish_at: Math.floor(row.publish_at ?? 0),
 				}
 			} else {
-				throw new FrontsPublishIntentError('missing_podcast_audio', row.id, message)
+				throw new FrontsPublishIntentError(failure.code, row.id, failure.message)
 			}
 		}
 	}

package/src/engine/fronts-publish.ts

@@ -26,7 +26,15 @@
 
 import type { ContentType, FrontsPublishStatus } from '../schema/types.js'
 import type { D1Database } from './d1.js'
+import { FrontsScheduleOverflowError } from './fronts-publish-intent.js'
+import { podcastPublishBlocker } from './podcast-source.js'
 import { type PublicationReconciler, publishOne } from './publication.js'
+import {
+	assertCurrentPublicationSnapshot,
+	PublicationCurrentSnapshotError,
+	snapshotRecord,
+} from './publication-current-guard.js'
+import { getContentSnapshot } from './publisher.js'
 
 /** The five lifecycle states foundryd reports for a Fronts publish intent. */
 export const FRONTS_PUBLISH_STATUSES: readonly FrontsPublishStatus[] = [
@@ -101,12 +109,13 @@ export async function listFrontsPublishSchedule(
 			`SELECT id, type, slug, title, channel, publish_at, fronts_publish_status
 			 FROM content_items
 			 WHERE status = 'scheduled'
+			   AND deleted_at IS NULL
 			   AND publish_at IS NOT NULL
 			   AND publish_at <= ?
 			 ORDER BY publish_at ASC
 			 LIMIT ?`,
 		)
-		.bind(options.toSeconds, limit)
+		.bind(options.toSeconds, limit + 1)
 		.all<{
 			id: string
 			type: ContentType
@@ -116,6 +125,7 @@ export async function listFrontsPublishSchedule(
 			publish_at: number
 			fronts_publish_status: FrontsPublishStatus | null
 		}>()
+	if ((result.results?.length ?? 0) > limit) throw new FrontsScheduleOverflowError(limit)
 	return (result.results ?? []).map((row) => ({
 		id: row.id,
 		type: row.type,
@@ -149,6 +159,14 @@ export interface FrontsPublishCallbackInput {
 	error?: string | null
 	/** Reference time (unix seconds), for tests. Defaults to Date.now(). */
 	now?: number
+	/** Optional occurrence evidence carried by current publish workers. */
+	publishAt?: number | null
+	/** The route supplies the same host hook used by the editorial publish action. */
+	checkReadiness?: (item: {
+		id: string
+		type: ContentType
+		status: string
+	}) => Promise<{ ready: boolean; blockers?: string[]; message?: string }>
 }
 
 export interface FrontsPublishCallbackResult {
@@ -163,6 +181,8 @@ export interface FrontsPublishCallbackResult {
 	contentFound: boolean
 	/** Set when a `live` callback could not be committed through the ledger. */
 	ledgerError: string | null
+	/** A retryable hold or stale/cancelled snapshot; never consumes event_id. */
+	rejection?: { code: string; status: 404 | 409 | 503; blockers?: string[]; message: string }
 }
 
 function hasReceipt(receipt: FrontsPublishReceipt | null | undefined): boolean {
@@ -231,9 +251,117 @@ export async function applyFrontsPublishCallback(
 	let attemptId: string | null = null
 	let ledgerError: string | null = null
 	const shouldPublish = input.status === 'live' && hasReceipt(input.receipt)
+	if (shouldPublish && item.status === 'published') {
+		const current = await getContentSnapshot(db, input.contentId)
+		if (
+			!current ||
+			!(await matchesCommittedCallback(
+				db,
+				input.contentId,
+				current,
+				await hashReceiptIdentity(input.receipt),
+				input,
+			))
+		) {
+			return {
+				ok: false,
+				deduped: false,
+				status: input.status,
+				published: false,
+				attemptId: null,
+				contentFound: true,
+				ledgerError: null,
+				rejection: {
+					code: 'publish_snapshot_changed',
+					status: 409,
+					message: 'The committed publication does not match this callback.',
+				},
+			}
+		}
+	}
 	if (shouldPublish && item.status !== 'published') {
+		const reject = (
+			code: string,
+			status: 404 | 409 | 503,
+			message: string,
+			blockers?: string[],
+		): FrontsPublishCallbackResult => ({
+			ok: false,
+			deduped: false,
+			status: input.status,
+			published: false,
+			attemptId: null,
+			contentFound: true,
+			ledgerError: null,
+			rejection: { code, status, message, ...(blockers ? { blockers } : {}) },
+		})
+		const expectedSnapshot = await getContentSnapshot(db, input.contentId)
+		const expectedItem = snapshotRecord(expectedSnapshot?.item)
+		if (
+			!expectedSnapshot ||
+			expectedItem.deleted_at != null ||
+			expectedItem.status !== 'scheduled'
+		) {
+			return reject('content_not_scheduled', 404, 'Content is no longer scheduled for publication.')
+		}
+		if (
+			(input.version != null && input.version !== expectedItem.canonical_version) ||
+			(input.publishAt != null && input.publishAt !== expectedItem.publish_at)
+		) {
+			return reject(
+				'publish_snapshot_changed',
+				409,
+				'The scheduled publication has been superseded.',
+			)
+		}
+		if (
+			typeof expectedItem.publish_at !== 'number' ||
+			!Number.isFinite(expectedItem.publish_at) ||
+			expectedItem.publish_at > now
+		) {
+			return reject(
+				'publish_not_ready',
+				503,
+				'The current scheduled publication time has not arrived.',
+				['publish_not_due'],
+			)
+		}
+		const blocker =
+			expectedItem.type === 'podcast'
+				? podcastPublishBlocker(snapshotRecord(expectedSnapshot.content))
+				: null
+		if (blocker) return reject('publish_not_ready', 503, blocker.message, [blocker.code])
+		if (input.checkReadiness) {
+			let timeout: ReturnType<typeof setTimeout> | undefined
+			try {
+				const readiness = await Promise.race([
+					input.checkReadiness({
+						id: input.contentId,
+						type: expectedItem.type as ContentType,
+						status: 'scheduled',
+					}),
+					new Promise<never>((_resolve, rejectTimeout) => {
+						timeout = setTimeout(() => rejectTimeout(new Error('readiness timed out')), 10_000)
+					}),
+				])
+				if (readiness.ready !== true)
+					return reject(
+						'publish_not_ready',
+						503,
+						readiness.message || 'Content is not ready for publication.',
+						readiness.blockers,
+					)
+			} catch {
+				return reject('publish_not_ready', 503, 'Publish readiness could not be verified.', [
+					'readiness_unavailable',
+				])
+			} finally {
+				if (timeout !== undefined) clearTimeout(timeout)
+			}
+		}
+		const receiptIdentity = await hashReceiptIdentity(input.receipt)
+		const receiptSummary = summarizeReceipt(input.receipt)
 		try {
-			const receiptSummary = summarizeReceipt(input.receipt)
 			const surface: PublicationReconciler = {
 				name: 'fronts',
 				async prepare() {
@@ -250,20 +378,43 @@ export async function applyFrontsPublishCallback(
 				...(publishedAt !== null ? { publishedAt } : {}),
 				createdBy: 'foundry.fronts-publish',
 				surfaces: [surface],
+				expectedCurrentSnapshot: expectedSnapshot,
+				expectedReceiptIdentity: receiptIdentity,
 			})
 			attemptId = receipt.attemptId
 			published = true
 		} catch (error) {
-			// publishOne can throw when a concurrent/superseding publish already
-			// moved the canonical pointer (the item ends up published anyway) — treat
-			// that as success. Any other failure is recorded and surfaced loudly.
+			// A concurrently published row may belong to a newer editor/source
+			// revision. Only a matching committed snapshot and full receipt prove
+			// this callback's success; status='published' alone proves nothing.
 			const reread = await db
 				.prepare('SELECT status FROM content_items WHERE id = ? LIMIT 1')
 				.bind(input.contentId)
 				.first<{ status: string }>()
 			if (reread?.status === 'published') {
+				if (
+					!(await matchesCommittedCallback(db, input.contentId, expectedSnapshot, receiptIdentity))
+				) {
+					return reject(
+						'publish_snapshot_changed',
+						409,
+						'A different publication superseded this callback.',
+					)
+				}
 				published = true
 			} else {
+				if (error instanceof PublicationCurrentSnapshotError)
+					return reject('publish_snapshot_changed', 409, error.message)
+				const current = await getContentSnapshot(db, input.contentId)
+				try {
+					assertCurrentPublicationSnapshot(current ?? {}, expectedSnapshot)
+				} catch {
+					return reject(
+						'publish_snapshot_changed',
+						409,
+						'Scheduled content or media changed before publication.',
+					)
+				}
 				ledgerError = error instanceof Error ? error.message : String(error)
 			}
 		}
@@ -348,6 +499,73 @@ export async function applyFrontsPublishCallback(
 	}
 }
 
+async function hashReceiptIdentity(
+	receipt: FrontsPublishReceipt | null | undefined,
+): Promise<string> {
+	const bytes = new TextEncoder().encode(
+		JSON.stringify([
+			'fronts-publish-receipt.v1',
+			receipt?.published_urls ?? null,
+			receipt?.platform_post_ids ?? null,
+			receipt?.sha256 ?? null,
+		]),
+	)
+	const digest = await crypto.subtle.digest('SHA-256', bytes)
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+async function matchesCommittedCallback(
+	db: D1Database,
+	contentId: string,
+	expectedSnapshot: Record<string, unknown>,
+	receiptIdentity: string,
+	input?: Pick<FrontsPublishCallbackInput, 'version' | 'publishAt'>,
+): Promise<boolean> {
+	const current = await db
+		.prepare(`SELECT r.id AS revision_id, r.payload_json, a.receipts_json
+		FROM content_items c
+		JOIN content_revisions r ON r.id = c.published_revision_id AND r.content_id = c.id
+		JOIN content_publication_attempts a ON a.revision_id = r.id AND a.content_id = c.id
+		WHERE c.id = ? AND c.status = 'published' AND c.deleted_at IS NULL
+		AND r.created_by = 'foundry.fronts-publish' AND a.operation = 'publish' AND a.state = 'committed'
+		LIMIT 1`)
+		.bind(contentId)
+		.first<{ revision_id: string; payload_json: string; receipts_json: string }>()
+	if (!current) return false
+	try {
+		const snapshot = snapshotRecord(JSON.parse(current.payload_json))
+		if (snapshot.publication_receipt_identity !== receiptIdentity) return false
+		const committedItem = snapshotRecord(snapshot.item)
+		const expectedItem = snapshotRecord(expectedSnapshot.item)
+		if (expectedItem.status === 'published') {
+			if (
+				expectedItem.published_revision_id !== current.revision_id ||
+				expectedItem.publish_at != null ||
+				(input?.version != null && input.version !== committedItem.canonical_version) ||
+				(input?.publishAt != null && input.publishAt !== committedItem.publish_at)
+			)
+				return false
+			// Commit deliberately changes only these scheduled guard fields.
+			// Every source/editor field must still match the immutable revision.
+			expectedSnapshot = {
+				...expectedSnapshot,
+				item: { ...expectedItem, status: 'scheduled', publish_at: committedItem.publish_at },
+			}
+		}
+		assertCurrentPublicationSnapshot(snapshot, expectedSnapshot)
+		const receipts: unknown = JSON.parse(current.receipts_json)
+		return (
+			Array.isArray(receipts) &&
+			receipts.some((value) => {
+				const receipt = snapshotRecord(value)
+				return receipt.name === 'fronts' && receipt.phase === 'commit' && receipt.status === 'ok'
+			})
+		)
+	} catch {
+		return false
+	}
+}
+
 /** Replay a stored callback outcome by event_id, or null when not yet recorded. */
 async function readStoredOutcome(
 	db: D1Database,

package/src/engine/index.ts

@@ -155,6 +155,10 @@ export {
 	type OgCardSpecOpts,
 	type OgImageRenderer,
 } from './og-render.js'
+export {
+	type FrontsPodcastSourceSnapshot,
+	frontsPodcastSourceGeneration,
+} from './podcast-source.js'
 // Bounded one-item publication kernel.
 export {
 	ContentArchiveImportLimitError,

package/src/engine/podcast-source.ts

@@ -0,0 +1,82 @@
+/** Current CMS evidence used by the signed schedule and media callback guards. */
+export interface FrontsPodcastSourceSnapshot {
+	content_id: string
+	slug: string
+	canonical_version: number
+	processing_source_url: string | null
+	processing_source_kind: string | null
+	processing_trigger_token: string | null
+}
+
+/**
+ * Stable over polling, machine media callbacks and rescheduling. Canonical
+ * editor/source changes invalidate the old production. Neither the raw source
+ * token nor URL needs to appear in callback/notification identities.
+ */
+export async function frontsPodcastSourceGeneration(
+	input: FrontsPodcastSourceSnapshot,
+): Promise<string> {
+	const bytes = new TextEncoder().encode(
+		JSON.stringify([
+			'fronts-podcast-source.v1',
+			input.content_id,
+			input.slug,
+			input.canonical_version,
+			input.processing_source_url,
+			input.processing_source_kind,
+			input.processing_trigger_token,
+		]),
+	)
+	const digest = await crypto.subtle.digest('SHA-256', bytes)
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+export type PodcastPublishBlockerCode =
+	| 'missing_podcast_audio'
+	| 'podcast_transcript_pending'
+	| 'podcast_source_duration_unavailable'
+
+/** Portable minimum; hosts may enforce additional object/access checks. */
+export function podcastPublishBlocker(
+	content:
+		| {
+				audio_r2_key?: unknown
+				transcript?: unknown
+				processing_source_url?: unknown
+				duration_seconds?: unknown
+		  }
+		| null
+		| undefined,
+): { code: PodcastPublishBlockerCode; message: string } | null {
+	if (typeof content?.audio_r2_key !== 'string' || !content.audio_r2_key.trim()) {
+		return { code: 'missing_podcast_audio', message: 'Podcast audio is not ready.' }
+	}
+	if (typeof content.transcript !== 'string' || !content.transcript.trim()) {
+		return { code: 'podcast_transcript_pending', message: 'Podcast transcript is not ready.' }
+	}
+	if (
+		typeof content.processing_source_url === 'string' &&
+		content.processing_source_url.trim() &&
+		(typeof content.duration_seconds !== 'number' ||
+			!Number.isFinite(content.duration_seconds) ||
+			content.duration_seconds <= 0)
+	) {
+		return {
+			code: 'podcast_source_duration_unavailable',
+			message: 'Podcast source duration is not verified.',
+		}
+	}
+	return null
+}
+
+export function validPodcastSourceUrl(value: string | null | undefined): value is string {
+	if (!value || !/^https:\/\/\S+$/.test(value) || Array.from(value).length > 2048) return false
+	try {
+		const url = new URL(value)
+		return (
+			url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !url.hash
+		)
+	} catch {
+		return false
+	}
+}