@growth-labs/cms 0.8.2 → 0.8.4

package/src/engine/fronts-publish.ts

@@ -24,7 +24,14 @@
 // additive and gated by FRONTS_PUBLISH_ENABLED (default ON — a rollback lever,
 // not a dark-staging gate).
 
+import type { LlmDispatch } from '../providers/types.js'
 import type { ContentType, FrontsPublishStatus } from '../schema/types.js'
+import {
+	applyGeneratedContentDek,
+	generateContentDekSuggestion,
+	loadDekGenerationContextFromSnapshot,
+} from './ai-dek.js'
+import { parseLockedFields } from './ai-writeback.js'
 import type { D1Database } from './d1.js'
 import { FrontsScheduleOverflowError } from './fronts-publish-intent.js'
 import { podcastPublishBlocker } from './podcast-source.js'
@@ -35,6 +42,7 @@ import {
 	snapshotRecord,
 } from './publication-current-guard.js'
 import { getContentSnapshot } from './publisher.js'
+import { getRevision } from './revisions.js'
 
 /** The five lifecycle states foundryd reports for a Fronts publish intent. */
 export const FRONTS_PUBLISH_STATUSES: readonly FrontsPublishStatus[] = [
@@ -161,6 +169,8 @@ export interface FrontsPublishCallbackInput {
 	now?: number
 	/** Optional occurrence evidence carried by current publish workers. */
 	publishAt?: number | null
+	/** Optional existing CMS LLM hook for best-effort missing-dek generation. */
+	llm?: LlmDispatch
 	/** The route supplies the same host hook used by the editorial publish action. */
 	checkReadiness?: (item: {
 		id: string
@@ -183,6 +193,10 @@ export interface FrontsPublishCallbackResult {
 	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 }
+	/** Safe post-commit reason for a missing-dek editor notification. */
+	dekFailureReason?: 'ai_generation_unavailable' | 'ai_generation_timeout' | null
+	/** Existing lifecycle payload fields, present only for this call's committed publication. */
+	publishedItem?: { id: string; type: ContentType; title: string } | null
 }
 
 function hasReceipt(receipt: FrontsPublishReceipt | null | undefined): boolean {
@@ -210,6 +224,8 @@ function resolveOccurredAtSeconds(
 	return Math.min(seconds, now)
 }
 
+class DekGenerationTimeoutError extends Error {}
+
 /**
  * Apply one foundryd publish-callback. Idempotent by `event_id`: a repeat
  * delivery returns the stored outcome without re-applying. See the module
@@ -228,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,
@@ -243,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,
@@ -250,6 +297,8 @@ export async function applyFrontsPublishCallback(
 	let published = item.status === 'published'
 	let attemptId: string | null = null
 	let ledgerError: string | null = null
+	let committedDekFailureReason: FrontsPublishCallbackResult['dekFailureReason'] = null
+	let committedPublishedItem: FrontsPublishCallbackResult['publishedItem'] = null
 	const shouldPublish = input.status === 'live' && hasReceipt(input.receipt)
 	if (shouldPublish && item.status === 'published') {
 		const current = await getContentSnapshot(db, input.contentId)
@@ -326,9 +375,88 @@ export async function applyFrontsPublishCallback(
 				['publish_not_due'],
 			)
 		}
+		let dekFailureReason: FrontsPublishCallbackResult['dekFailureReason'] = null
+		const initialExcerpt =
+			typeof expectedItem.excerpt === 'string' ? expectedItem.excerpt.trim() : ''
+		const initialLocks = parseLockedFields(
+			typeof expectedItem.ai_locked_fields === 'string' ? expectedItem.ai_locked_fields : null,
+		)
+		if (!initialExcerpt && !initialLocks.includes('excerpt')) {
+			if (!input.llm) {
+				dekFailureReason = 'ai_generation_unavailable'
+			} else {
+				const deadlineAt = performance.now() + 8_000
+				let timeout: ReturnType<typeof setTimeout> | undefined
+				try {
+					const generated = await Promise.race([
+						(async () => {
+							const context = await loadDekGenerationContextFromSnapshot(db, expectedSnapshot)
+							if (!context) {
+								return {
+									context: null,
+									suggestion: {
+										status: 'unavailable' as const,
+										dek: null,
+										reason: 'unavailable',
+									},
+								}
+							}
+							return {
+								context,
+								suggestion: await generateContentDekSuggestion({
+									context,
+									llm: input.llm!,
+								}),
+							}
+						})(),
+						new Promise<never>((_resolve, rejectTimeout) => {
+							timeout = setTimeout(() => rejectTimeout(new DekGenerationTimeoutError()), 8_000)
+						}),
+					])
+					if (generated.suggestion.status !== 'generated') {
+						dekFailureReason = 'ai_generation_unavailable'
+					} else if (!generated.context || performance.now() >= deadlineAt) {
+						dekFailureReason = 'ai_generation_timeout'
+					} else {
+						const applied = await applyGeneratedContentDek({
+							db,
+							contentId: input.contentId,
+							dek: generated.suggestion.dek,
+							context: generated.context,
+							expectedPublicationSnapshot: expectedSnapshot,
+						})
+						if (applied.status === 'unavailable') dekFailureReason = 'ai_generation_unavailable'
+					}
+				} catch (error) {
+					dekFailureReason =
+						error instanceof DekGenerationTimeoutError
+							? 'ai_generation_timeout'
+							: 'ai_generation_unavailable'
+				} finally {
+					if (timeout !== undefined) clearTimeout(timeout)
+				}
+			}
+		}
+
+		const currentSnapshot = await getContentSnapshot(db, input.contentId)
+		try {
+			assertCurrentPublicationSnapshot(currentSnapshot ?? {}, expectedSnapshot)
+		} catch {
+			return reject(
+				'publish_snapshot_changed',
+				409,
+				'Scheduled content or media changed before publication.',
+			)
+		}
+		const currentItem = snapshotRecord(currentSnapshot?.item)
+		const currentExcerpt = typeof currentItem.excerpt === 'string' ? currentItem.excerpt.trim() : ''
+		const currentLocks = parseLockedFields(
+			typeof currentItem.ai_locked_fields === 'string' ? currentItem.ai_locked_fields : null,
+		)
+		if (currentExcerpt || currentLocks.includes('excerpt')) dekFailureReason = null
 		const blocker =
-			expectedItem.type === 'podcast'
-				? podcastPublishBlocker(snapshotRecord(expectedSnapshot.content))
+			currentItem.type === 'podcast'
+				? podcastPublishBlocker(snapshotRecord(currentSnapshot?.content))
 				: null
 		if (blocker) return reject('publish_not_ready', 503, blocker.message, [blocker.code])
 		if (input.checkReadiness) {
@@ -337,7 +465,7 @@ export async function applyFrontsPublishCallback(
 				const readiness = await Promise.race([
 					input.checkReadiness({
 						id: input.contentId,
-						type: expectedItem.type as ContentType,
+						type: currentItem.type as ContentType,
 						status: 'scheduled',
 					}),
 					new Promise<never>((_resolve, rejectTimeout) => {
@@ -378,11 +506,29 @@ export async function applyFrontsPublishCallback(
 				...(publishedAt !== null ? { publishedAt } : {}),
 				createdBy: 'foundry.fronts-publish',
 				surfaces: [surface],
-				expectedCurrentSnapshot: expectedSnapshot,
+				expectedCurrentSnapshot: currentSnapshot!,
 				expectedReceiptIdentity: receiptIdentity,
 			})
 			attemptId = receipt.attemptId
 			published = true
+			const committedRevision = await getRevision(db, input.contentId, receipt.revisionId)
+			if (attemptId && committedRevision) {
+				const committedItem = snapshotRecord(committedRevision.payload.item)
+				const committedExcerpt =
+					typeof committedItem.excerpt === 'string' ? committedItem.excerpt.trim() : ''
+				const committedLocks = parseLockedFields(
+					typeof committedItem.ai_locked_fields === 'string'
+						? committedItem.ai_locked_fields
+						: null,
+				)
+				committedDekFailureReason =
+					committedExcerpt || committedLocks.includes('excerpt') ? null : dekFailureReason
+				committedPublishedItem = {
+					id: String(committedItem.id ?? input.contentId),
+					type: committedItem.type as ContentType,
+					title: String(committedItem.title ?? ''),
+				}
+			}
 		} catch (error) {
 			// A concurrently published row may belong to a newer editor/source
 			// revision. Only a matching committed snapshot and full receipt prove
@@ -428,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(
@@ -441,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
@@ -496,6 +650,8 @@ export async function applyFrontsPublishCallback(
 		attemptId,
 		contentFound: true,
 		ledgerError,
+		dekFailureReason: committedDekFailureReason,
+		publishedItem: committedPublishedItem,
 	}
 }
 

package/src/engine/index.ts

@@ -78,6 +78,7 @@ export type { D1Database, D1DatabaseSession, D1PreparedStatement, D1Result } fro
 export {
 	applyFoundryCallback,
 	type CallbackInput,
+	createFoundrySourceCaptureToken,
 	type DispatchResult,
 	dispatchToFoundry,
 	type ProcessingState,
@@ -161,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/podcast-source.ts

@@ -9,19 +9,21 @@ export interface FrontsPodcastSourceSnapshot {
 }
 
 /**
- * Stable over polling, machine media callbacks and rescheduling. Canonical
- * editor/source changes invalidate the old production. Neither the raw source
+ * V1 captures keep their canonical-version binding. New v2 captures remain
+ * stable over editorial metadata edits, polling, callbacks and rescheduling;
+ * source/slug/token changes invalidate production. Neither the raw source
  * token nor URL needs to appear in callback/notification identities.
  */
 export async function frontsPodcastSourceGeneration(
 	input: FrontsPodcastSourceSnapshot,
 ): Promise<string> {
+	const version = input.processing_trigger_token?.startsWith('fronts-source-v2:') ? 2 : 1
 	const bytes = new TextEncoder().encode(
 		JSON.stringify([
-			'fronts-podcast-source.v1',
+			`fronts-podcast-source.v${version}`,
 			input.content_id,
 			input.slug,
-			input.canonical_version,
+			...(version === 1 ? [input.canonical_version] : []),
 			input.processing_source_url,
 			input.processing_source_kind,
 			input.processing_trigger_token,

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)}))
 	))`
 }