@growth-labs/cms 0.6.5 → 0.6.7

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

@@ -0,0 +1,87 @@
+/** A guard lives with its revision, so retries retain the same editorial proof. */
+export const CURRENT_PUBLICATION_GUARD = 'cms.scheduled-publication-current.v1'
+
+export class PublicationCurrentSnapshotError extends Error {
+	constructor() {
+		super('Scheduled content or media changed before publication.')
+		this.name = 'PublicationCurrentSnapshotError'
+	}
+}
+
+export function snapshotRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === 'object' && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {}
+}
+
+const ITEM_FIELDS = [
+	'id',
+	'type',
+	'slug',
+	'status',
+	'deleted_at',
+	'canonical_version',
+	'publish_at',
+] as const
+const PODCAST_FIELDS = [
+	'audio_r2_key',
+	'transcript',
+	'duration_seconds',
+	'processing_source_url',
+	'processing_source_kind',
+	'processing_trigger_token',
+] as const
+const VIDEO_FIELDS = [
+	'video_id',
+	'duration_seconds',
+	'processing_source_url',
+	'processing_source_kind',
+	'processing_trigger_token',
+	'processing_correlation_id',
+	'processing_state',
+	'hls_ready',
+	'hls_manifest_url',
+	'transcript_ready',
+	'transcript_url',
+] as const
+
+export function assertCurrentPublicationSnapshot(
+	current: Record<string, unknown>,
+	expected: Record<string, unknown>,
+): void {
+	const item = snapshotRecord(current.item)
+	const expectedItem = snapshotRecord(expected.item)
+	if (
+		item.status !== 'scheduled' ||
+		item.deleted_at != null ||
+		ITEM_FIELDS.some((field) => item[field] !== expectedItem[field])
+	) {
+		throw new PublicationCurrentSnapshotError()
+	}
+	const fields =
+		item.type === 'podcast' ? PODCAST_FIELDS : item.type === 'video' ? VIDEO_FIELDS : []
+	const content = snapshotRecord(current.content)
+	const expectedContent = snapshotRecord(expected.content)
+	if (fields.some((field) => content[field] !== expectedContent[field]))
+		throw new PublicationCurrentSnapshotError()
+}
+
+/** Uses the immutable revision in the existing pointer CAS; no second write. */
+export function currentPublicationSqlGuard(revisionAlias: string): string {
+	const item = (field: string) => `json_extract(${revisionAlias}.payload_json, '$.item.${field}')`
+	const content = (field: string) =>
+		`json_extract(${revisionAlias}.payload_json, '$.content.${field}')`
+	const matches = (table: string, fields: readonly string[]) => `EXISTS (
+		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 ')}
+	)`
+	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
+		AND ${ITEM_FIELDS.filter((field) => field !== 'deleted_at')
+			.map((field) => `content_items.${field} IS ${item(field)}`)
+			.join(' AND ')}
+		AND (${item('type')} <> 'podcast' OR ${matches('podcast_content', PODCAST_FIELDS)})
+		AND (${item('type')} <> 'video' OR ${matches('video_content', VIDEO_FIELDS)})
+	))`
+}

package/src/engine/publication.ts

@@ -11,6 +11,11 @@ import {
 	serializeContentMetadata,
 } from './content-metadata.js'
 import type { D1Database, D1Result } from './d1.js'
+import {
+	assertCurrentPublicationSnapshot,
+	CURRENT_PUBLICATION_GUARD,
+	currentPublicationSqlGuard,
+} from './publication-current-guard.js'
 import { evaluateArticleBody } from './publish-guard.js'
 import {
 	type CreateContentInput,
@@ -81,6 +86,10 @@ export interface PublishOneInput {
 	requiredSurfaceNames?: string[]
 	packageVersion?: string | null
 	surfaceHookTimeoutMs?: number
+	/** Machine publication must still describe this scheduled editorial/media snapshot. */
+	expectedCurrentSnapshot?: Record<string, unknown>
+	/** Digest of the external receipt bound to a guarded machine publication. */
+	expectedReceiptIdentity?: string
 }
 
 export interface PublishOneReceipt {
@@ -763,6 +772,8 @@ async function createRevisionAndPublicationAttempt(
 		packageVersion: string | null
 		now: number
 		createdBy?: string | null
+		expectedCurrentSnapshot?: Record<string, unknown>
+		expectedReceiptIdentity?: string
 	},
 ): Promise<{
 	revisionId: string
@@ -771,6 +782,15 @@ async function createRevisionAndPublicationAttempt(
 }> {
 	const snapshot = await getContentSnapshot(db, input.contentId)
 	if (!snapshot) throw new PublicationNotFoundError(`content not found: ${input.contentId}`)
+	if (input.expectedCurrentSnapshot) {
+		assertCurrentPublicationSnapshot(snapshot, input.expectedCurrentSnapshot)
+		snapshot.publication_guard = CURRENT_PUBLICATION_GUARD
+		if (input.expectedReceiptIdentity !== undefined) {
+			if (!/^[a-f0-9]{64}$/.test(input.expectedReceiptIdentity))
+				throw new Error('Invalid guarded publication receipt identity')
+			snapshot.publication_receipt_identity = input.expectedReceiptIdentity
+		}
+	}
 	assertPublicationSnapshotBodyValid(snapshot, input.contentId)
 	const revisionId = crypto.randomUUID()
 	const attemptId = crypto.randomUUID()
@@ -1597,6 +1617,7 @@ async function movePointerAndBeginCommit(
 		  AND target_revision.content_id = ?
 		  AND json_type(target_revision.payload_json, '$.item.slug') = 'text'
 		  AND length(json_extract(target_revision.payload_json, '$.item.slug')) BETWEEN 1 AND 512
+		  ${attempt.operation === 'publish' ? `AND ${currentPublicationSqlGuard('target_revision')}` : ''}
 		  AND NOT EXISTS (
 		    SELECT 1
 		    FROM content_items other_item
@@ -1816,6 +1837,8 @@ export async function publishOne(
 		packageVersion: input.packageVersion ?? null,
 		now,
 		createdBy: input.createdBy,
+		expectedCurrentSnapshot: input.expectedCurrentSnapshot,
+		expectedReceiptIdentity: input.expectedReceiptIdentity,
 	})
 	const reconciliationInput: PublicationReconciliationInput = {
 		operation: 'publish',

package/src/engine/publisher.ts

@@ -882,7 +882,20 @@ export async function updateContentItem(
 			const audioR2Key = hasOwn(podcastContent, 'audioR2Key')
 				? (podcastContent.audioR2Key ?? current.audio_r2_key)
 				: current.audio_r2_key
-			const sourceChanged = audioR2Key !== current.audio_r2_key
+			const audioChanged = audioR2Key !== current.audio_r2_key
+			const sourceUrl = hasOwn(podcastContent, 'processingSourceUrl')
+				? (podcastContent.processingSourceUrl ?? null)
+				: audioChanged
+					? null
+					: current.processing_source_url
+			const sourceKind = hasOwn(podcastContent, 'processingSourceKind')
+				? (podcastContent.processingSourceKind ?? null)
+				: audioChanged
+					? null
+					: current.processing_source_kind
+			const capturedSourceChanged =
+				sourceUrl !== current.processing_source_url || sourceKind !== current.processing_source_kind
+			const sourceChanged = audioChanged || capturedSourceChanged
 			const durationProvided = hasOwn(podcastContent, 'durationSeconds')
 			const reusesSavedDuration =
 				!sourceChanged &&
@@ -892,7 +905,7 @@ export async function updateContentItem(
 				: await resolveMediaDuration(
 						db,
 						'podcast',
-						audioR2Key,
+						capturedSourceChanged ? sourceUrl : audioR2Key,
 						durationProvided ? podcastContent.durationSeconds : undefined,
 					)
 			const replacementTranscriptProvided =
@@ -906,18 +919,14 @@ export async function updateContentItem(
 					: replacementTranscriptProvided
 						? (podcastContent.transcript as string)
 						: current.transcript,
-				audioR2Key,
+				audioR2Key: capturedSourceChanged && !audioChanged ? '' : audioR2Key,
 				durationSeconds:
 					durationProvided || sourceChanged
 						? resolvedDuration
 						: (resolvedDuration ?? current.duration_seconds),
 				processingTriggerToken: sourceChanged ? null : current.processing_trigger_token,
-				sourceUrl: hasOwn(podcastContent, 'processingSourceUrl')
-					? (podcastContent.processingSourceUrl ?? null)
-					: current.processing_source_url,
-				sourceKind: hasOwn(podcastContent, 'processingSourceKind')
-					? (podcastContent.processingSourceKind ?? null)
-					: current.processing_source_kind,
+				sourceUrl,
+				sourceKind,
 			}
 		} else {
 			podcastUpdatePlan = null
@@ -1146,10 +1155,9 @@ export async function updateContentItem(
 		metadata_json = ?,
         updated_at = unixepoch(),
         -- The canonical revision counter behind the Fronts publish intent id
-        -- masthead:<content_id>:<version> (migration 0027). This is the ONE seam
-        -- that advances it, so an intent identity changes exactly when the item's
-        -- canonical content does -- and never on a fronts_publish_status marker
-        -- write or a schedule poll.
+        -- masthead:<content_id>:<version> (migration 0027). Canonical edits and
+        -- actual delete/restore/archive transitions advance it; scheduling,
+        -- fronts_publish_status marker writes and polls keep it stable.
         canonical_version = canonical_version + 1
       WHERE id = ?
       `,

package/src/engine/soft-delete.ts

@@ -8,7 +8,7 @@ export async function softDeleteContent(
 	const ts = now ?? Math.floor(Date.now() / 1000)
 	const res = await db
 		.prepare(
-			'UPDATE content_items SET deleted_at = ?, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NULL',
+			'UPDATE content_items SET deleted_at = ?, updated_at = unixepoch(), canonical_version = canonical_version + 1 WHERE id = ? AND deleted_at IS NULL',
 		)
 		.bind(ts, id)
 		.run()
@@ -18,7 +18,7 @@ export async function softDeleteContent(
 export async function restoreContent(db: D1Database, id: string): Promise<boolean> {
 	const res = await db
 		.prepare(
-			'UPDATE content_items SET deleted_at = NULL, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NOT NULL',
+			'UPDATE content_items SET deleted_at = NULL, updated_at = unixepoch(), canonical_version = canonical_version + 1 WHERE id = ? AND deleted_at IS NOT NULL',
 		)
 		.bind(id)
 		.run()

package/src/providers/types.ts

@@ -397,8 +397,13 @@ export interface FoundryJobSpec {
 	description?: string | null
 	processingTriggerTokenHash?: string
 }
+export interface FoundryDispatchResult {
+	correlationId: string
+	/** Return source evidence; the CMS owns its atomic capture with the token. */
+	podcastSource?: { url: string; kind: 'https' }
+}
 export interface FoundryDispatch {
-	dispatchVideo(jobSpec: FoundryJobSpec): Promise<{ correlationId: string }>
+	dispatchVideo(jobSpec: FoundryJobSpec): Promise<FoundryDispatchResult>
 	getJob(correlationId: string): Promise<{ state: string } | null>
 }
 

package/src/routes/content.ts

@@ -197,6 +197,8 @@ export interface ContentRouteConfig extends CmsRouteConfig {
 	dispatchFaq?: DispatchFaqHook
 	/** Optional host-specific readiness guard. A not-ready result blocks publish. */
 	publishReadiness?: PublishReadinessHook
+	/** Host's existing production rollback control; omitted means enabled. */
+	podcastSourceProductionEnabled?: boolean
 	/** Internal machine-route constraint: atomically update only in this status. */
 	updateStatusConstraint?: ContentStatus
 	/**
@@ -705,7 +707,9 @@ async function getContentPayload(ctx: RouteContext, type: string, id: string) {
 	if (type === 'podcast') {
 		return ctx.db
 			.prepare(
-				'SELECT transcript, audio_r2_key, duration_seconds FROM podcast_content WHERE content_id = ? LIMIT 1',
+				`SELECT transcript, audio_r2_key, duration_seconds,
+					processing_source_url, processing_source_kind
+				 FROM podcast_content WHERE content_id = ? LIMIT 1`,
 			)
 			.bind(id)
 			.first()
@@ -1888,7 +1892,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (action === 'archive') {
 				await ctx.db
 					.prepare(
-						"UPDATE content_items SET status = 'archived', updated_at = unixepoch() WHERE id = ?",
+						"UPDATE content_items SET status = 'archived', updated_at = unixepoch(), canonical_version = canonical_version + 1 WHERE id = ? AND status <> 'archived'",
 					)
 					.bind(id)
 					.run()

package/src/routes/fronts-publish.ts

@@ -29,9 +29,13 @@ import {
 	isFrontsPublishEnabled,
 	listFrontsPublishSchedule,
 } from '../engine/fronts-publish.js'
-import { hydrateFrontsPublishIntents } from '../engine/fronts-publish-intent.js'
+import {
+	FrontsScheduleOverflowError,
+	hydrateFrontsPublishIntents,
+} from '../engine/fronts-publish-intent.js'
 import { publicUrlFor } from '../ui/screens/public-url.js'
-import { type CmsRouteConfig, resolveConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import type { ContentRouteConfig } from './content.js'
 import { json, type RouteContext } from './context.js'
 
 /**
@@ -112,6 +116,7 @@ const CallbackSchema = z
 		intent_id: z.string().min(1).nullish(),
 		content_id: z.string().min(1),
 		version: z.number().int().nullish(),
+		publish_at: z.number().int().positive().nullish(),
 		correlation_id: z.string().min(1).nullish(),
 		status: z.enum(['queued', 'publishing', 'live', 'late', 'failed']),
 		occurred_at: z.union([z.string(), z.number()]).nullish(),
@@ -151,7 +156,7 @@ function parseWindow(
 	return { fromSeconds, toSeconds }
 }
 
-export function createFrontsPublishRoutes(config: CmsRouteConfig): FrontsPublishRouteHandlers {
+export function createFrontsPublishRoutes(config: ContentRouteConfig): FrontsPublishRouteHandlers {
 	const resolved = resolveConfig(config)
 	return {
 		async schedule(ctx) {
@@ -184,28 +189,37 @@ export function createFrontsPublishRoutes(config: CmsRouteConfig): FrontsPublish
 			// predicate, and `incomplete` names every due item that cannot form a
 			// complete intent, so a missing canonical field is an explicit, visible
 			// contract error rather than a silently short `intents` array.
-			const items = await listFrontsPublishSchedule(ctx.db, {
-				toSeconds: window.toSeconds,
-				nowSeconds: now,
-			})
-			const hydrated = await hydrateFrontsPublishIntents(ctx.db, {
-				toSeconds: window.toSeconds,
-				nowSeconds: now,
-				mediaPublicDomain: resolved.mediaPublicDomain,
-				// Site-RELATIVE paths: the CMS does not know the site origin, and the
-				// consumer joins its own trusted configured origin. A host-supplied
-				// origin is deliberately deferred (packages-docs/cms.md).
-				resolveContentUrl: (row) => publicUrlFor(row),
-			})
-			return json({
-				ok: true,
-				now,
-				window: { from: window.fromSeconds, to: window.toSeconds },
-				count: items.length,
-				items,
-				intents: hydrated.intents,
-				incomplete: hydrated.incomplete,
-			})
+			try {
+				const items = await listFrontsPublishSchedule(ctx.db, {
+					toSeconds: window.toSeconds,
+					nowSeconds: now,
+				})
+				const hydrated = await hydrateFrontsPublishIntents(ctx.db, {
+					toSeconds: window.toSeconds,
+					nowSeconds: now,
+					mediaPublicDomain: resolved.mediaPublicDomain,
+					podcastSourceProductionEnabled: config.podcastSourceProductionEnabled,
+					// Site-RELATIVE paths: the CMS does not know the site origin, and the
+					// consumer joins its own trusted configured origin. A host-supplied
+					// origin is deliberately deferred (packages-docs/cms.md).
+					resolveContentUrl: (row) => publicUrlFor(row),
+				})
+				return json({
+					ok: true,
+					now,
+					window: { from: window.fromSeconds, to: window.toSeconds },
+					count: items.length,
+					items,
+					intents: hydrated.intents,
+					incomplete: hydrated.incomplete,
+				})
+			} catch (error) {
+				if (error instanceof FrontsScheduleOverflowError) {
+					console.error(`[cms] fronts/schedule unavailable: ${error.message}`)
+					return json({ ok: false, error: 'schedule_overflow', message: error.message }, 503)
+				}
+				throw error
+			}
 		},
 
 		async publishCallback(ctx) {
@@ -253,16 +267,40 @@ export function createFrontsPublishRoutes(config: CmsRouteConfig): FrontsPublish
 				intentId: parsed.data.intent_id ?? null,
 				contentId: parsed.data.content_id,
 				version: parsed.data.version ?? null,
+				publishAt: parsed.data.publish_at ?? null,
 				correlationId: parsed.data.correlation_id ?? null,
 				status: parsed.data.status,
 				occurredAt: parsed.data.occurred_at ?? null,
 				receipt: parsed.data.receipt ?? null,
 				error: parsed.data.error ?? null,
+				checkReadiness: config.publishReadiness
+					? (item) =>
+							config.publishReadiness!({
+								ctx,
+								contentId: item.id,
+								type: item.type,
+								status: item.status,
+							})
+					: undefined,
 			})
 
 			if (!result.contentFound) {
 				return json({ error: 'content_not_found', contentId: parsed.data.content_id }, 404)
 			}
+			if (result.rejection) {
+				console.warn(
+					`[cms] fronts/publish-callback rejected for content ${parsed.data.content_id}: ${result.rejection.code}`,
+				)
+				return json(
+					{
+						ok: false,
+						error: result.rejection.code,
+						message: result.rejection.message,
+						...(result.rejection.blockers ? { blockers: result.rejection.blockers } : {}),
+					},
+					result.rejection.status,
+				)
+			}
 			if (result.ledgerError) {
 				// A confirmed `live` that could not be committed through the ledger is a
 				// hard, loud failure — never a silent zero.

package/src/routes/index.ts

@@ -312,7 +312,7 @@ export function createCmsRoutes(
 			authz: config.authz,
 			activeWorkspaceId: config.activeWorkspaceId,
 		}),
-		frontsPublish: createFrontsPublishRoutes(base),
+		frontsPublish: createFrontsPublishRoutes(config),
 		foundryPublish: createFoundryPublishRoutes(config),
 	}
 }

package/src/ui/api/_content-config.ts

@@ -24,6 +24,7 @@ type CmsHooksLocals = ContentRouteConfig['hooks'] & {
 	dispatchFaq?: DispatchFaqHook
 	dispatchWebhook?: DispatchWebhookHook
 	publishReadiness?: PublishReadinessHook
+	podcastSourceProductionEnabled?: boolean
 }
 
 /**
@@ -73,5 +74,6 @@ export function toContentConfig(c: APIContext): ContentRouteConfig {
 		dispatchFaq: hooks.dispatchFaq,
 		dispatchWebhook: hooks.dispatchWebhook,
 		publishReadiness: hooks.publishReadiness,
+		podcastSourceProductionEnabled: hooks.podcastSourceProductionEnabled,
 	}
 }

package/src/ui/api/fronts/publish-callback.ts

@@ -5,14 +5,8 @@
 // content_publication_attempts 2PC ledger. HMAC-SHA256 (X-Foundry-Signature vs
 // env.FOUNDRY_HMAC_SECRET) only — NOT behind requirePublisher.
 import type { APIContext } from 'astro'
-import type { RouteContext } from '../../../routes/context.js'
 import { createFrontsPublishRoutes } from '../../../routes/fronts-publish.js'
-import { buildSiteAuthz } from '../_authz.js'
-
-function toCtx(c: APIContext): RouteContext {
-	const env = (c.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
-	return { request: c.request, params: {}, db: env.SITE_DB as RouteContext['db'], env }
-}
+import { toContentConfig, toContentCtx } from '../_content-config.js'
 
 export const POST = (c: APIContext) =>
-	createFrontsPublishRoutes({ authz: buildSiteAuthz(c) }).publishCallback(toCtx(c))
+	createFrontsPublishRoutes(toContentConfig(c)).publishCallback(toContentCtx(c, {}))

package/src/ui/api/fronts/schedule.ts

@@ -5,14 +5,8 @@
 // env.FOUNDRY_HMAC_SECRET) only — NOT behind requirePublisher. Sibling of the
 // content foundry-callback / insights-ingest M2M routes.
 import type { APIContext } from 'astro'
-import type { RouteContext } from '../../../routes/context.js'
 import { createFrontsPublishRoutes } from '../../../routes/fronts-publish.js'
-import { buildSiteAuthz } from '../_authz.js'
-
-function toCtx(c: APIContext): RouteContext {
-	const env = (c.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
-	return { request: c.request, params: {}, db: env.SITE_DB as RouteContext['db'], env }
-}
+import { toContentConfig, toContentCtx } from '../_content-config.js'
 
 export const GET = (c: APIContext) =>
-	createFrontsPublishRoutes({ authz: buildSiteAuthz(c) }).schedule(toCtx(c))
+	createFrontsPublishRoutes(toContentConfig(c)).schedule(toContentCtx(c, {}))

package/src/ui/inspector/PublishTab.tsx

@@ -316,7 +316,7 @@ export function PublishTab({
 				{/* Scheduled date + time inputs */}
 				{showScheduleControls && (
 					<div style={schedGrid} className="fade-only">
-						<Field label="Date">
+						<Field label="Date (UTC)">
 							<input
 								className="input"
 								type="date"
@@ -324,7 +324,7 @@ export function PublishTab({
 								onChange={(e) => setSchedDate(e.target.value)}
 							/>
 						</Field>
-						<Field label="Time">
+						<Field label="Time (UTC)">
 							<input
 								className="input"
 								type="time"