@growth-labs/cms 0.8.3 → 0.8.5

package/src/engine/foundry-dispatch.ts

@@ -10,8 +10,9 @@
 // on `processing_trigger_token` and deduplicated on `event_id`.
 
 import type { FoundryDispatch } from '../providers/types.js'
-import type { D1Database, D1Result } from './d1.js'
+import type { D1Database, D1PreparedStatement, D1Result } from './d1.js'
 import { validPodcastSourceUrl } from './podcast-source.js'
+import { mediaPublicationCaptureGuard } from './publication-current-guard.js'
 
 interface PodcastDispatchSnapshot {
 	content_id: string
@@ -132,7 +133,9 @@ export async function dispatchToFoundry(
 ): Promise<DispatchResult> {
 	const content = await db
 		.prepare(
-			'SELECT id, type, slug, title, description, canonical_version, status, deleted_at FROM content_items WHERE id = ? LIMIT 1',
+			`SELECT id, type, slug, title, description, canonical_version, status, deleted_at,
+			visibility, published_revision_id, published_at, publish_at, publish_tz,
+			fronts_publish_status, fronts_publish_trigger_token FROM content_items WHERE id = ? LIMIT 1`,
 		)
 		.bind(contentId)
 		.first<{
@@ -144,6 +147,13 @@ export async function dispatchToFoundry(
 			canonical_version: number
 			status: string
 			deleted_at: number | null
+			visibility: string
+			published_revision_id: string | null
+			published_at: number | null
+			publish_at: number | null
+			publish_tz: string | null
+			fronts_publish_status: string | null
+			fronts_publish_trigger_token: string | null
 		}>()
 	if (!content) {
 		throw new Error(`dispatchToFoundry: content ${contentId} not found`)
@@ -215,12 +225,21 @@ export async function dispatchToFoundry(
 			throw new Error(`dispatchToFoundry: podcast ${contentId} is inactive`)
 		}
 		podcastSnapshot = podcastRow
-		sourceUrl = podcastRow.audio_r2_key?.trim() ?? ''
+		const selectedSource = podcastRow.processing_source_url?.trim()
+		if (
+			selectedSource &&
+			(podcastRow.processing_source_kind !== 'https' || !validPodcastSourceUrl(selectedSource))
+		) {
+			throw new Error(`dispatchToFoundry: content ${contentId} has an invalid podcast source URL`)
+		}
+		sourceUrl = selectedSource || podcastRow.audio_r2_key?.trim() || ''
 		if (!sourceUrl) {
-			throw new Error(`dispatchToFoundry: content ${contentId} has no podcast audio R2 key`)
+			throw new Error(
+				`dispatchToFoundry: content ${contentId} has no podcast source or audio R2 key`,
+			)
 		}
 		kind = 'podcast'
-		sourceKind = 'r2_key'
+		sourceKind = selectedSource ? 'https' : 'r2_key'
 		videoId = normalizeVideoId(content.slug, content.slug)
 		durationSeconds = podcastRow.duration_seconds
 	}
@@ -249,6 +268,7 @@ export async function dispatchToFoundry(
 
 	const triggerToken = createFoundrySourceCaptureToken()
 	const processingTriggerTokenHash = `sha256:${await sha256Hex(triggerToken)}`
+	const publicationGuard = mediaPublicationCaptureGuard(content, processingTriggerTokenHash)
 	const { correlationId, podcastSource } = await hook.dispatchVideo({
 		contentId,
 		sourceUrl,
@@ -273,6 +293,7 @@ export async function dispatchToFoundry(
              processing_source_kind = ?,
              processing_correlation_id = ?,
              processing_trigger_token = ?,
+             processing_publication_guard = ?,
              processing_started_at = ?,
              processing_completed_at = NULL,
              processing_last_event_at = NULL,
@@ -288,13 +309,17 @@ export async function dispatchToFoundry(
          AND processing_trigger_token IS ? AND processing_correlation_id IS ?
          AND EXISTS (SELECT 1 FROM content_items ci WHERE ci.id = video_content.content_id
          AND ci.type = 'video' AND ci.slug = ? AND ci.canonical_version = ?
-         AND ci.status = ? AND ci.deleted_at IS NULL)`,
+         AND ci.status = ? AND ci.deleted_at IS NULL
+         AND ci.visibility IS ? AND ci.published_revision_id IS ? AND ci.published_at IS ?
+         AND ci.publish_at IS ? AND ci.publish_tz IS ?
+         AND ci.fronts_publish_status IS ? AND ci.fronts_publish_trigger_token IS ?)`,
 			)
 			.bind(
 				videoId,
 				sourceKind,
 				correlationId,
 				triggerToken,
+				publicationGuard,
 				now,
 				contentId,
 				videoRow.video_id,
@@ -306,6 +331,13 @@ export async function dispatchToFoundry(
 				content.slug,
 				content.canonical_version,
 				content.status,
+				content.visibility,
+				content.published_revision_id,
+				content.published_at,
+				content.publish_at,
+				content.publish_tz,
+				content.fronts_publish_status,
+				content.fronts_publish_trigger_token,
 			)
 			.run()
 		if (written.meta?.changes !== 1)
@@ -330,16 +362,20 @@ export async function dispatchToFoundry(
 		// source/audio/editor snapshot is still current. No stale acknowledgement
 		// can restore a replaced source or overwrite a newer processing token.
 		const written = await db
-			.prepare(`UPDATE podcast_content SET processing_source_url = ?, processing_source_kind = ?, processing_trigger_token = ?, transcript = ''
+			.prepare(`UPDATE podcast_content SET processing_source_url = ?, processing_source_kind = ?, processing_trigger_token = ?, processing_publication_guard = ?, processing_state = 'queued', processing_error = NULL, transcript = ''
 			WHERE content_id = ? AND audio_r2_key IS ? AND duration_seconds IS ? AND transcript IS ?
 			AND processing_source_url IS ? AND processing_source_kind IS ? AND processing_trigger_token IS ?
 			AND EXISTS (SELECT 1 FROM content_items ci WHERE ci.id = podcast_content.content_id
 			AND ci.type = 'podcast' AND ci.slug = ? AND ci.canonical_version = ?
-			AND ci.status = ? AND ci.deleted_at IS NULL)`)
+			AND ci.status = ? AND ci.deleted_at IS NULL
+			AND ci.visibility IS ? AND ci.published_revision_id IS ? AND ci.published_at IS ?
+			AND ci.publish_at IS ? AND ci.publish_tz IS ?
+			AND ci.fronts_publish_status IS ? AND ci.fronts_publish_trigger_token IS ?)`)
 			.bind(
 				capturedUrl,
 				capturedKind,
 				triggerToken,
+				publicationGuard,
 				contentId,
 				podcastSnapshot.audio_r2_key,
 				podcastSnapshot.duration_seconds,
@@ -350,6 +386,13 @@ export async function dispatchToFoundry(
 				content.slug,
 				content.canonical_version,
 				content.status,
+				content.visibility,
+				content.published_revision_id,
+				content.published_at,
+				content.publish_at,
+				content.publish_tz,
+				content.fronts_publish_status,
+				content.fronts_publish_trigger_token,
 			)
 			.run()
 		if (written.meta?.changes !== 1)
@@ -423,14 +466,19 @@ export async function applyFoundryCallback(db: D1Database, input: CallbackInput)
 		return false // no matching job for this trigger token
 	}
 
-	// Insert the event row.
+	// A failed event is consumed atomically with terminal state and guard revocation.
+	// Otherwise a transient media write failure would make its retry a no-op.
 	const now = Math.floor(Date.now() / 1000)
-	await db
+	const eventStatement = db
 		.prepare(
 			'INSERT INTO foundry_callback_events (event_id, event_kind, correlation_id, received_at) VALUES (?, ?, ?, ?)',
 		)
 		.bind(eventId, eventKind, correlationId, now)
-		.run()
+	if (nextState !== 'failed') await eventStatement.run()
+	const applyMediaUpdate = async (statement: D1PreparedStatement): Promise<D1Result> =>
+		nextState === 'failed'
+			? (await db.batch([statement, eventStatement]))[0]!
+			: await statement.run()
 
 	// Advance the state machine.
 	const isTerminal = (TERMINAL_STATES as string[]).includes(nextState)
@@ -442,23 +490,31 @@ export async function applyFoundryCallback(db: D1Database, input: CallbackInput)
 			typeof durationSeconds === 'number' && Number.isFinite(durationSeconds)
 				? Math.max(0, Math.floor(durationSeconds))
 				: null
-		if (nextTranscript !== null || nextDurationSeconds !== null) {
-			const updated = await db
-				.prepare(
-					`UPDATE podcast_content
-					SET transcript = CASE WHEN ? THEN ? ELSE transcript END,
+		{
+			const updated = await applyMediaUpdate(
+				db
+					.prepare(
+						`UPDATE podcast_content
+					SET processing_state = CASE WHEN processing_state = 'failed' THEN processing_state ELSE ? END,
+						processing_error = CASE WHEN ? = 'failed' THEN ? ELSE processing_error END,
+						processing_publication_guard = CASE WHEN ? = 'failed' THEN NULL ELSE processing_publication_guard END,
+                        transcript = CASE WHEN ? THEN ? ELSE transcript END,
 						duration_seconds = CASE WHEN ? THEN ? ELSE duration_seconds END
 					WHERE content_id = ? AND processing_trigger_token = ?`,
-				)
-				.bind(
-					nextTranscript !== null ? 1 : 0,
-					nextTranscript,
-					nextDurationSeconds !== null ? 1 : 0,
-					nextDurationSeconds,
-					podcastRow.content_id,
-					triggerToken,
-				)
-				.run()
+					)
+					.bind(
+						nextState,
+						nextState,
+						error ?? null,
+						nextState,
+						nextTranscript !== null ? 1 : 0,
+						nextTranscript,
+						nextDurationSeconds !== null ? 1 : 0,
+						nextDurationSeconds,
+						podcastRow.content_id,
+						triggerToken,
+					),
+			)
 			if (updated.meta?.changes !== 1) return false
 		}
 
@@ -504,23 +560,25 @@ export async function applyFoundryCallback(db: D1Database, input: CallbackInput)
 	let updated: D1Result
 
 	if (nextState === 'failed') {
-		updated = await db
-			.prepare(
-				`UPDATE video_content
-         SET processing_state = ?,
+		updated = await applyMediaUpdate(
+			db
+				.prepare(
+					`UPDATE video_content
+         SET processing_state = CASE WHEN processing_state = 'failed' THEN processing_state ELSE ? END,
+             processing_publication_guard = NULL,
              processing_last_event_at = ?,
              processing_completed_at = ?,
              processing_error = ?
          WHERE content_id = ? AND processing_trigger_token = ?`,
-			)
-			.bind(nextState, now, now, error ?? null, row.content_id, triggerToken)
-			.run()
+				)
+				.bind(nextState, now, now, error ?? null, row.content_id, triggerToken),
+		)
 	} else if (isTerminal) {
 		// 'ready'
 		updated = await db
 			.prepare(
 				`UPDATE video_content
-         SET processing_state = ?,
+         SET processing_state = CASE WHEN processing_state = 'failed' THEN processing_state ELSE ? END,
              processing_last_event_at = ?,
              processing_completed_at = ?
          WHERE content_id = ? AND processing_trigger_token = ?`,
@@ -530,7 +588,7 @@ export async function applyFoundryCallback(db: D1Database, input: CallbackInput)
 	} else {
 		updated = await db
 			.prepare(
-				'UPDATE video_content SET processing_state = ?, processing_last_event_at = ? WHERE content_id = ? AND processing_trigger_token = ?',
+				"UPDATE video_content SET processing_state = CASE WHEN processing_state = 'failed' THEN processing_state ELSE ? END, processing_last_event_at = ? WHERE content_id = ? AND processing_trigger_token = ?",
 			)
 			.bind(nextState, now, row.content_id, triggerToken)
 			.run()

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

@@ -538,6 +538,7 @@ interface VideoRefRow {
 	processing_source_url: string | null
 	processing_source_kind: string | null
 	processing_trigger_token: string | null
+	processing_state: string | null
 	processing_correlation_id: string | null
 }
 
@@ -549,6 +550,7 @@ interface PodcastRefRow {
 	processing_source_url: string | null
 	processing_source_kind: string | null
 	processing_trigger_token: string | null
+	processing_state: string | null
 }
 
 interface MediaRow {
@@ -682,7 +684,7 @@ async function loadContentRefSources(
 			.prepare(
 				`SELECT content_id, hls_ready, hls_manifest_url, hls_poster_url, duration_seconds,
 				        thumbnail_image_id, processing_source_url, processing_source_kind,
-				        processing_trigger_token, processing_correlation_id
+				        processing_trigger_token, processing_correlation_id, processing_state
 				 FROM video_content WHERE content_id IN (${placeholders(videoIds.length)})`,
 			)
 			.bind(...videoIds)
@@ -694,7 +696,7 @@ async function loadContentRefSources(
 	if (podcastIds.length > 0) {
 		const res = await db
 			.prepare(
-				`SELECT content_id, transcript, audio_r2_key, duration_seconds, processing_source_url, processing_source_kind, processing_trigger_token FROM podcast_content
+				`SELECT content_id, transcript, audio_r2_key, duration_seconds, processing_source_url, processing_source_kind, processing_trigger_token, processing_state FROM podcast_content
 				 WHERE content_id IN (${placeholders(podcastIds.length)})`,
 			)
 			.bind(...podcastIds)
@@ -753,6 +755,7 @@ async function videoSourceRef(
 			'Video source duration is not verified.',
 		)
 	}
+	if (found.processing_state !== 'queued' || !found.processing_trigger_token?.trim()) return null
 	return {
 		kind: 'https',
 		url: found.processing_source_url,
@@ -791,6 +794,7 @@ async function podcastSourceRef(
 			'Podcast source duration is not verified.',
 		)
 	}
+	if (found.processing_state !== 'queued' || !found.processing_trigger_token?.trim()) return null
 	return {
 		kind: 'https',
 		url: found.processing_source_url,
@@ -846,11 +850,11 @@ export async function hydrateFrontsMediaPreparations(
 		WHERE deleted_at IS NULL AND status IN ('draft', 'review', 'scheduled', 'published')
 		AND ((type = 'video' AND ? = 1 AND EXISTS (
 			SELECT 1 FROM video_content v WHERE v.content_id = content_items.id
-			AND v.processing_trigger_token IS NOT NULL
+			AND v.processing_trigger_token IS NOT NULL AND v.processing_state = 'queued'
 			AND (v.hls_ready <> 1 OR v.hls_manifest_url IS NULL OR v.transcript_ready <> 1)))
 		OR (type = 'podcast' AND ? = 1 AND EXISTS (
 			SELECT 1 FROM podcast_content p WHERE p.content_id = content_items.id
-			AND p.processing_trigger_token IS NOT NULL
+			AND p.processing_trigger_token IS NOT NULL AND p.processing_state = 'queued'
 			AND (trim(COALESCE(p.audio_r2_key, '')) = '' OR trim(COALESCE(p.transcript, '')) = ''))))
 		ORDER BY created_at ASC, id ASC LIMIT ?`)
 		.bind(

package/src/engine/fronts-publish.ts

@@ -244,9 +244,17 @@ export async function applyFrontsPublishCallback(
 	// 2. Resolve the target item. A missing item is NOT recorded, so a retry can
 	//    still land once the item exists.
 	const item = await db
-		.prepare('SELECT id, status, fronts_publish_status FROM content_items WHERE id = ? LIMIT 1')
+		.prepare(
+			'SELECT id, status, fronts_publish_status, canonical_version, publish_at FROM content_items WHERE id = ? LIMIT 1',
+		)
 		.bind(input.contentId)
-		.first<{ id: string; status: string; fronts_publish_status: FrontsPublishStatus | null }>()
+		.first<{
+			id: string
+			status: string
+			fronts_publish_status: FrontsPublishStatus | null
+			canonical_version: number
+			publish_at: number | null
+		}>()
 	if (!item) {
 		return {
 			ok: false,
@@ -259,6 +267,29 @@ export async function applyFrontsPublishCallback(
 		}
 	}
 
+	const staleOccurrence = (): FrontsPublishCallbackResult => ({
+		ok: false,
+		deduped: false,
+		status: input.status,
+		published: false,
+		attemptId: null,
+		contentFound: true,
+		ledgerError: null,
+		rejection: {
+			code: 'publish_snapshot_changed',
+			status: 409,
+			message: 'The publication occurrence has been superseded.',
+		},
+	})
+	// Non-live callbacks carry the same occurrence authority as a live receipt.
+	// An old progress/failure event must not strand a newly queued publication.
+	if (
+		(input.version != null && input.version !== item.canonical_version) ||
+		(item.status !== 'published' && input.publishAt != null && input.publishAt !== item.publish_at)
+	) {
+		return staleOccurrence()
+	}
+
 	// 3. On a confirmed `live` WITH a receipt, drive the publish through the 2PC
 	//    ledger — record attempt + commit — flipping the item to published.
 	//    A `live` on an already-published item just confirms it (no re-publish,
@@ -543,9 +574,9 @@ export async function applyFrontsPublishCallback(
 	//    ordering and the terminal `live`/published state.
 	const latestSeenRow = await db
 		.prepare(
-			'SELECT MAX(occurred_at) AS latest FROM fronts_publish_events WHERE content_id = ? AND occurred_at IS NOT NULL',
+			'SELECT MAX(occurred_at) AS latest FROM fronts_publish_events WHERE content_id = ? AND occurred_at IS NOT NULL AND (? IS NULL OR version IS ?)',
 		)
-		.bind(input.contentId)
+		.bind(input.contentId, input.version ?? null, input.version ?? null)
 		.first<{ latest: number | null }>()
 	if (
 		shouldApplyFrontsMarker(
@@ -556,12 +587,20 @@ export async function applyFrontsPublishCallback(
 			latestSeenRow?.latest ?? null,
 		)
 	) {
-		await db
+		const marker = await db
 			.prepare(
-				'UPDATE content_items SET fronts_publish_status = ?, updated_at = unixepoch() WHERE id = ?',
+				`UPDATE content_items SET fronts_publish_status = ?, updated_at = unixepoch()
+				WHERE id = ? AND canonical_version = ? AND status = ? AND publish_at IS ? AND deleted_at IS NULL`,
+			)
+			.bind(
+				input.status,
+				input.contentId,
+				item.canonical_version,
+				published ? 'published' : item.status,
+				published ? null : item.publish_at,
 			)
-			.bind(input.status, input.contentId)
 			.run()
+		if (marker.meta?.changes !== 1) return staleOccurrence()
 	}
 
 	// 5. Record the durable, idempotent event row (the "processed" marker). The

package/src/engine/index.ts

@@ -162,9 +162,12 @@ export {
 } from './podcast-source.js'
 // Bounded one-item publication kernel.
 export {
+	type CommitPreparedPublishedMediaInput,
+	type CommitPreparedPublishedMediaResult,
 	ContentArchiveImportLimitError,
 	type ContentArchiveInput,
 	type ContentArchiveItem,
+	commitPreparedPublishedMedia,
 	DEFAULT_PENDING_PUBLICATION_ATTEMPT_LIMIT,
 	DEFAULT_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS,
 	type ImportContentArchiveOptions,

package/src/engine/publication-current-guard.ts

@@ -1,5 +1,38 @@
 /** A guard lives with its revision, so retries retain the same editorial proof. */
 export const CURRENT_PUBLICATION_GUARD = 'cms.scheduled-publication-current.v1'
+export const CURRENT_MEDIA_PUBLICATION_GUARD = 'cms.published-media-current.v1'
+
+export const MEDIA_PUBLICATION_ITEM_FIELDS = [
+	'id',
+	'type',
+	'slug',
+	'status',
+	'deleted_at',
+	'canonical_version',
+	'visibility',
+	'published_revision_id',
+	'published_at',
+	'publish_at',
+	'publish_tz',
+	'fronts_publish_status',
+	'fronts_publish_trigger_token',
+] as const
+
+/** Bound to the capture CAS, separately from the reusable media generation. */
+export function mediaPublicationCaptureGuard(
+	item: Record<string, unknown>,
+	triggerTokenHash: string,
+): string | null {
+	if (item.status !== 'published' || !item.published_revision_id || item.deleted_at != null)
+		return null
+	return JSON.stringify({
+		version: 1,
+		trigger_token_hash: triggerTokenHash,
+		item: Object.fromEntries(
+			MEDIA_PUBLICATION_ITEM_FIELDS.map((field) => [field, item[field] ?? null]),
+		),
+	})
+}
 
 export class PublicationCurrentSnapshotError extends Error {
 	constructor() {
@@ -45,6 +78,42 @@ const VIDEO_FIELDS = [
 	'transcript_url',
 ] as const
 
+export const PUBLISHED_VIDEO_MEDIA_FIELDS = [
+	...VIDEO_FIELDS,
+	'hls_poster_url',
+	'source_fetched',
+	'processing_started_at',
+	'processing_completed_at',
+	'processing_last_event_at',
+	'processing_error',
+] as const
+export const PUBLISHED_PODCAST_MEDIA_FIELDS = PODCAST_FIELDS
+// Delivery observation timestamps can advance on a duplicate/captions event;
+// they do not change the prepared bytes or authorize a different source.
+const MEDIA_VIDEO_GUARD_FIELDS = [...VIDEO_FIELDS, 'hls_poster_url'] as const
+
+export function assertCurrentMediaPublicationSnapshot(
+	current: Record<string, unknown>,
+	expected: Record<string, unknown>,
+): void {
+	const item = snapshotRecord(current.item)
+	const expectedItem = snapshotRecord(expected.item)
+	const content = snapshotRecord(current.content)
+	const expectedContent = snapshotRecord(expected.content)
+	const fields = item.type === 'video' ? MEDIA_VIDEO_GUARD_FIELDS : PUBLISHED_PODCAST_MEDIA_FIELDS
+	if (
+		item.status !== 'published' ||
+		item.deleted_at != null ||
+		!['video', 'podcast'].includes(String(item.type)) ||
+		MEDIA_PUBLICATION_ITEM_FIELDS.some((field) => item[field] !== expectedItem[field]) ||
+		[...fields, 'processing_publication_guard'].some(
+			(field) => content[field] !== expectedContent[field],
+		)
+	) {
+		throw new PublicationCurrentSnapshotError()
+	}
+}
+
 export function assertCurrentPublicationSnapshot(
 	current: Record<string, unknown>,
 	expected: Record<string, unknown>,
@@ -75,6 +144,17 @@ export function currentPublicationSqlGuard(revisionAlias: string): string {
 		SELECT 1 FROM ${table} current_media WHERE current_media.content_id = content_items.id
 		AND ${fields.map((field) => `current_media.${field} IS ${content(field)}`).join(' AND ')}
 	)`
+	const mediaItem = (field: string) =>
+		`json_extract(${revisionAlias}.payload_json, '$.publication_current_snapshot.item.${field}')`
+	const mediaMatches = (table: string, fields: readonly string[]) => `EXISTS (
+		SELECT 1 FROM ${table} current_media WHERE current_media.content_id = content_items.id
+		AND ${[...fields, 'processing_publication_guard']
+			.map(
+				(field) =>
+					`current_media.${field} IS json_extract(${revisionAlias}.payload_json, '$.publication_current_snapshot.content.${field}')`,
+			)
+			.join(' AND ')}
+	)`
 	return `(json_extract(${revisionAlias}.payload_json, '$.publication_guard') IS NULL OR (
 		json_extract(${revisionAlias}.payload_json, '$.publication_guard') = '${CURRENT_PUBLICATION_GUARD}'
 		AND content_items.status = 'scheduled' AND content_items.deleted_at IS NULL
@@ -83,5 +163,11 @@ export function currentPublicationSqlGuard(revisionAlias: string): string {
 			.join(' AND ')}
 		AND (${item('type')} <> 'podcast' OR ${matches('podcast_content', PODCAST_FIELDS)})
 		AND (${item('type')} <> 'video' OR ${matches('video_content', VIDEO_FIELDS)})
+	) OR (
+		json_extract(${revisionAlias}.payload_json, '$.publication_guard') = '${CURRENT_MEDIA_PUBLICATION_GUARD}'
+		AND content_items.status = 'published' AND content_items.deleted_at IS NULL
+		AND ${MEDIA_PUBLICATION_ITEM_FIELDS.map((field) => `content_items.${field} IS ${mediaItem(field)}`).join(' AND ')}
+		AND ((${mediaItem('type')} = 'video' AND ${mediaMatches('video_content', MEDIA_VIDEO_GUARD_FIELDS)})
+		OR (${mediaItem('type')} = 'podcast' AND ${mediaMatches('podcast_content', PUBLISHED_PODCAST_MEDIA_FIELDS)}))
 	))`
 }