@growth-labs/cms 0.8.33 → 0.8.38

package/src/foundry-emit.ts

@@ -35,6 +35,15 @@ const HERO_IMAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9._\-/]*$/
 export const FoundryArticleV2Schema = z
 	.object({
 		schemaVersion: z.literal(FOUNDRY_ARTICLE_SCHEMA_VERSION),
+		createOnly: z.literal(true).optional(),
+		/** Actual CMS source revision pinned by a strategy-led improvement. */
+		expectedRevisionId: z.string().uuid().optional(),
+		/** Continue this writer's exact private snapshot, without adopting newer edits. */
+		expectedRequestSHA256: z
+			.string()
+			.regex(/^[a-f0-9]{64}$/)
+			.optional(),
+		expectedCanonicalVersion: z.number().int().positive().optional(),
 		slug: z.string().refine(isCanonicalSlug, {
 			message: 'slug must already be canonical: lowercase a-z, 0-9 and single hyphens, 3-512 chars',
 		}),
@@ -70,6 +79,19 @@ export const FoundryArticleV2Schema = z
 			.optional(),
 	})
 	.strict()
+	.refine(
+		(body) =>
+			(body.expectedRequestSHA256 === undefined) ===
+				(body.expectedCanonicalVersion === undefined) &&
+			!(
+				body.expectedRequestSHA256 &&
+				(body.createOnly || body.expectedRevisionId || body.adoptSourceId)
+			),
+		{
+			message: 'own working update requires both pins and cannot create or adopt',
+			path: ['expectedRequestSHA256'],
+		},
+	)
 	.refine((body) => !(body.hero_image_key && body.hero_image_url), {
 		message: 'send hero_image_key or hero_image_url, not both',
 		path: ['hero_image_key'],

package/src/routes/content-insights.ts

@@ -11,7 +11,11 @@ import {
 	undismissInsight,
 } from '../engine/content-insights.js'
 import { verifyHmac } from '../engine/foundry-dispatch.js'
-import { listPublishedContent, PublishedContentReadError } from '../engine/published-content.js'
+import {
+	getPublishedContentBySlug,
+	listPublishedContent,
+	PublishedContentReadError,
+} from '../engine/published-content.js'
 import { InsightsIngestPayloadSchema } from '../schema/insights-ingest.js'
 import { InsightDismissalReasonCodeSchema } from '../schema/types.js'
 import type { CmsRouteConfig } from './config.js'
@@ -21,6 +25,7 @@ import {
 	resolveFoundryHmacSecret as resolveFoundryHmacSecretForInputs,
 	verifyFoundrySignedRequest,
 } from './fronts-publish.js'
+import { readReadyImagePublicUrl } from './media-lib.js'
 
 const DismissSchema = z
 	.object({
@@ -56,6 +61,22 @@ const PublishedArticleStateSchema = z
 	})
 	.strict()
 
+const PublishedArticleSourceSchema = z
+	.object({
+		ok: z.literal(true),
+		schema: z.literal('cms.published-article-source.v1'),
+		site: z.string().min(1),
+		observed_at: z.string().datetime(),
+		article: PublishedArticleStateSchema.extend({
+			hero_image_url: z.string().url().nullable(),
+			body_markdown: z.string().min(1).max(1_000_000),
+			description: z.string().nullable(),
+			byline: z.string().nullable(),
+			tags: z.array(z.string()),
+		}).strict(),
+	})
+	.strict()
+
 const PublishedInputsResponseSchema = z
 	.object({
 		ok: z.literal(true),
@@ -76,6 +97,54 @@ async function publishedInputs(ctx: RouteContext, url: URL, siteId: string): Pro
 		return json({ error: 'invalid_published_mode' }, 400)
 	if (siteId === 'default') return json({ error: 'publication_identity_not_configured' }, 503)
 	if (url.searchParams.get('site') !== siteId) return json({ error: 'publication_mismatch' }, 403)
+	const articleSlug = url.searchParams.get('article')
+	if (articleSlug !== null) {
+		const slug = z
+			.string()
+			.min(1)
+			.max(512)
+			.regex(/^[a-z0-9][a-z0-9-]*$/)
+			.safeParse(articleSlug)
+		if (!slug.success || url.searchParams.has('cursor') || url.searchParams.has('limit'))
+			return json({ error: 'invalid_article_source_request' }, 400)
+		try {
+			const content = await getPublishedContentBySlug(ctx.db, slug.data)
+			if (!content || content.type !== 'article')
+				return json({ error: 'published_article_missing' }, 404)
+			const item = content.payload.item
+			const heroImageUrl = await readReadyImagePublicUrl(ctx.db, item.hero_image_id)
+			const result = PublishedArticleSourceSchema.safeParse({
+				ok: true,
+				schema: 'cms.published-article-source.v1',
+				site: siteId,
+				observed_at: new Date().toISOString(),
+				article: {
+					content_id: content.contentId,
+					revision_id: content.revisionId,
+					slug: content.slug,
+					title: item.title,
+					canonical_url: item.canonical_url ?? null,
+					published_at: content.publishedAt,
+					source_id: item.source_id ?? null,
+					youtube_video_id: content.metadata.videoId ?? null,
+					hero_image_id: item.hero_image_id ?? null,
+					hero_image_url: heroImageUrl,
+					hero_image_caption: item.hero_image_caption ?? null,
+					body_markdown: content.payload.content?.body_markdown,
+					description: item.description ?? null,
+					byline: item.byline ?? null,
+					tags: content.payload.tags,
+				},
+			})
+			if (!result.success) return json({ error: 'published_article_source_invalid' }, 409)
+			if (new TextEncoder().encode(JSON.stringify(result.data)).byteLength > 4 << 20)
+				return json({ error: 'published_article_source_too_large' }, 409)
+			return json(result.data)
+		} catch (error) {
+			if (error instanceof PublishedContentReadError) return json({ error: error.code }, 409)
+			throw error
+		}
+	}
 	const limit = z.coerce
 		.number()
 		.int()
@@ -137,7 +206,7 @@ function resolveRunDate(ctx: RouteContext): string {
 }
 
 /**
- * Resolve the HMAC secret from ctx.env.INSIGHTS_INGEST_HMAC_SECRET.
+ * Resolve the explicit legacy ingest binding, or the declared shared CMS machine binding for channel publications.
  * Supports both:
  *   - plain string (test injection: env: { INSIGHTS_INGEST_HMAC_SECRET: 'test-...' })
  *   - Secrets Store binding object { get(): Promise<string> } (production Workers binding)
@@ -146,21 +215,13 @@ function resolveRunDate(ctx: RouteContext): string {
 async function resolveIngestSecret(
 	env: Record<string, unknown> | undefined,
 ): Promise<string | null> {
-	const raw = env?.INSIGHTS_INGEST_HMAC_SECRET
-	if (typeof raw === 'string') return raw
-	if (
-		raw !== null &&
-		typeof raw === 'object' &&
-		typeof (raw as { get?: unknown }).get === 'function'
-	) {
-		try {
-			const val = await (raw as { get(): Promise<string> }).get()
-			if (typeof val === 'string' && val.length > 0) return val
-		} catch {
-			return null
-		}
-	}
-	return null
+	// Preserve explicit legacy ingest credentials, including their failures.
+	// Channel publications already declare the shared CMS machine binding.
+	const binding =
+		env?.INSIGHTS_INGEST_HMAC_SECRET === undefined
+			? 'CMS_FOUNDRY_HMAC_SECRET'
+			: 'INSIGHTS_INGEST_HMAC_SECRET'
+	return resolveFoundryHmacSecretForInputs(env, binding)
 }
 
 export interface ContentInsightsRouteConfig extends CmsRouteConfig {
@@ -277,7 +338,13 @@ export function createContentInsightsRoutes(
 		// HMAC-guarded machine ingest — NOT behind requirePublisher (sibling of foundryCallback).
 		async ingest(ctx) {
 			const hmacSecret = await resolveIngestSecret(ctx.env)
-			if (!hmacSecret) return json({ error: 'INSIGHTS_INGEST_HMAC_SECRET is not configured' }, 500)
+			if (!hmacSecret)
+				return json(
+					{
+						error: `${ctx.env?.INSIGHTS_INGEST_HMAC_SECRET === undefined ? 'CMS_FOUNDRY_HMAC_SECRET' : 'INSIGHTS_INGEST_HMAC_SECRET'} is not configured`,
+					},
+					500,
+				)
 
 			let rawBody: string
 			try {

package/src/routes/content.ts

@@ -235,6 +235,8 @@ export interface ContentRouteConfig extends CmsRouteConfig {
 	videoSourceProductionEnabled?: boolean
 	/** Internal machine-route constraint: atomically update only in this status. */
 	updateStatusConstraint?: ContentStatus
+	/** Internal machine-route pin; joins the existing status-constrained atomic batch. */
+	updateCanonicalVersionConstraint?: number
 	/**
 	 * Internal (Foundry machine route, M3-18): replaces ONLY the publish action's
 	 * commit step (publishContent + createRevision) with the caller's — publishOne
@@ -1807,6 +1809,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			try {
 				updated = await updateContentItem(ctx.db, id, parsed.data, {
 					requiredStatus: config.updateStatusConstraint,
+					expectedCanonicalVersion: config.updateCanonicalVersionConstraint,
 					...(expectedMediaSource ? { expectedMediaSource } : {}),
 				})
 			} catch (error) {
@@ -1821,6 +1824,9 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (updated.statusConflict) {
 				return json({ error: 'update_status_conflict', state: updated.statusConflict }, 409)
 			}
+			if (updated.canonicalVersionConflict) {
+				return json({ error: 'update_canonical_conflict' }, 409)
+			}
 			if (updated.mediaSourceConflict) {
 				return json({ error: 'media_source_conflict' }, 409)
 			}

package/src/routes/foundry-publish.ts

@@ -1,5 +1,6 @@
 import { isCanonicalHost, sha256Hex, verifyFoundryRequest } from '@growth-labs/foundry-signing'
 import { z } from 'zod'
+import { ContentMetadataSchema, mergePinnedArticleMetadata } from '../engine/content-metadata.js'
 import { type PublicationReconciler, publishOne } from '../engine/publication.js'
 import { PublicationCurrentSnapshotError } from '../engine/publication-current-guard.js'
 import { PublishContentValidationError } from '../engine/publisher.js'
@@ -9,7 +10,7 @@ import { type FoundryArticleV2, FoundryArticleV2Schema } from '../foundry-emit.j
 import { type ContentRouteConfig, createContentRoutes } from './content.js'
 import { json, type RouteContext } from './context.js'
 import { markFoundryMachineContext } from './machine-context.js'
-import { insertMediaAsset } from './media-lib.js'
+import { insertMediaAsset, readReadyImagePublicUrl } from './media-lib.js'
 
 const SOURCE_PREFIX = 'foundry:'
 
@@ -117,7 +118,10 @@ async function authenticate(
 	// host-bound foundry-cms-v2 string with this publication's CONFIGURED
 	// canonical host when it opted in (M3-18), else the legacy dot string,
 	// byte-for-byte as before.
-	const path = new URL(ctx.request.url).pathname
+	const url = new URL(ctx.request.url)
+	const path =
+		url.pathname +
+		(ctx.request.method === 'GET' && url.searchParams.has('working') ? url.search : '')
 	const verified = await verifyFoundryRequest(secret, {
 		method: ctx.request.method,
 		host: canonicalHost,
@@ -263,6 +267,9 @@ async function mapUpdateConflict(response: Response, id: string): Promise<Respon
 	if (response.status !== 409) return response
 	try {
 		const payload = (await response.clone().json()) as { error?: unknown; state?: unknown }
+		if (payload.error === 'update_canonical_conflict') {
+			return json({ error: 'human_edit_pending', external_id: id }, 409)
+		}
 		if (payload.error === 'update_status_conflict' && typeof payload.state === 'string') {
 			return approvalConflict(id, payload.state)
 		}
@@ -470,6 +477,7 @@ async function bindAdoption(
 	config: ContentRouteConfig,
 	id: string,
 	candidate: ContentCandidate,
+	expectedVersion?: number,
 ): Promise<boolean> {
 	const sourceId = `${SOURCE_PREFIX}${id}`
 	await ctx.db.batch([
@@ -477,9 +485,17 @@ async function bindAdoption(
 			.prepare(
 				`UPDATE content_items SET source_id = ?, updated_at = unixepoch()
 				 WHERE id = ? AND deleted_at IS NULL AND type = 'article' AND source_id = ?
-				   AND NOT EXISTS (SELECT 1 FROM cms_foundry_articles WHERE content_id = ?)`,
+				   AND NOT EXISTS (SELECT 1 FROM cms_foundry_articles WHERE content_id = ?)
+				   AND (? IS NULL OR canonical_version = ?)`,
 			)
-			.bind(sourceId, candidate.id, candidate.source_id, candidate.id),
+			.bind(
+				sourceId,
+				candidate.id,
+				candidate.source_id,
+				candidate.id,
+				expectedVersion ?? null,
+				expectedVersion ?? null,
+			),
 		ctx.db
 			.prepare(
 				`INSERT INTO cms_activity_log (id, workspace_id, user_id, action, target_id, target_title, type)
@@ -518,6 +534,27 @@ async function canonicalVersion(ctx: RouteContext, contentId: string): Promise<n
 	return row?.canonical_version ?? null
 }
 
+/** A signed improvement names the actual immutable CMS revision it read. */
+async function sourceRevisionVersion(
+	ctx: RouteContext,
+	contentId: string,
+	revisionId: string,
+): Promise<number | null> {
+	const revision = await getRevision(ctx.db, contentId, revisionId)
+	if (!revision) return null
+	const item = revision.payload.item as Record<string, unknown> | undefined
+	const version = item?.canonical_version
+	if (
+		item?.id !== contentId ||
+		item.type !== 'article' ||
+		typeof version !== 'number' ||
+		!Number.isSafeInteger(version) ||
+		version < 1
+	)
+		return null
+	return (await canonicalVersion(ctx, contentId)) === version ? version : null
+}
+
 /**
  * Record what this v2 PUT wrote as a History revision (the autosave/restore
  * mechanism; it never moves the published pointer), created_by `foundry` and
@@ -571,6 +608,67 @@ async function lastFoundryWriteSnapshot(
 	return revision ? { ...revision.payload } : null
 }
 
+const WorkingArticleSourceSchema = z
+	.object({
+		schema: z.literal('cms.foundry-working-article.v1'),
+		content_id: z.string().min(1),
+		canonical_version: z.number().int().nonnegative(),
+		title: z.string().min(1),
+		description: z.string().nullable(),
+		slug: z.string().min(1),
+		body_html: z.string().min(1).max(2_000_000),
+		hero_image_id: z.string().nullable(),
+		hero_image_url: z.string().url().nullable(),
+		metadata: ContentMetadataSchema,
+	})
+	.strict()
+
+async function workingArticleSource(ctx: RouteContext, row: FoundryArticleRow): Promise<Response> {
+	const snapshot = await lastFoundryWriteSnapshot(ctx, row)
+	if (!snapshot)
+		return json({ error: 'foundry_working_revision_changed', external_id: row.external_id }, 409)
+	const item = snapshot.item as Record<string, unknown>
+	const content = snapshot.content as Record<string, unknown>
+	let metadata: unknown
+	try {
+		metadata = JSON.parse(String(item.metadata_json ?? '{}'))
+	} catch {
+		return json({ error: 'working_source_metadata_invalid' }, 409)
+	}
+	const recorded = ContentMetadataSchema.safeParse(metadata)
+	if (!recorded.success) return json({ error: 'working_source_metadata_invalid' }, 409)
+	const allowed = new Set([
+		'preparation',
+		'seoDescription',
+		'credits',
+		'imageReview',
+		'faq',
+		'captionMoments',
+		'videoId',
+		'cmsSource',
+		'strategyWork',
+		'sourceRef',
+		'sourceRevisionId',
+		'adaptedAt',
+		'updatedAt',
+		'videoPublishedAt',
+	])
+	const result = WorkingArticleSourceSchema.safeParse({
+		schema: 'cms.foundry-working-article.v1',
+		content_id: row.content_id,
+		canonical_version: item.canonical_version,
+		title: item.title,
+		description: item.description ?? null,
+		slug: item.slug,
+		body_html: content?.body_html,
+		hero_image_id: item.hero_image_id ?? null,
+		hero_image_url: await readReadyImagePublicUrl(ctx.db, item.hero_image_id),
+		metadata: Object.fromEntries(Object.entries(recorded.data).filter(([key]) => allowed.has(key))),
+	})
+	if (!result.success) return json({ error: 'foundry_working_source_invalid' }, 409)
+	return json({ ...v2Receipt(row), working: result.data })
+}
+
 /** The v2 receipt: the four v1 fields plus the stored request hash. */
 function v2Receipt(
 	row: Pick<FoundryArticleRow, 'external_id' | 'receipt_id' | 'status' | 'slug' | 'request_sha256'>,
@@ -595,6 +693,29 @@ async function putV2(
 	const body = parsed.data
 
 	const prior = await findArticle(ctx, id)
+	let expectedWorkingVersion: number | undefined
+	if (body.expectedRequestSHA256) {
+		if (
+			!prior ||
+			(prior.request_sha256 !== body.expectedRequestSHA256 && prior.request_sha256 !== bodyHash)
+		)
+			return json({ error: 'foundry_working_revision_changed', external_id: id }, 409)
+		const snapshot = await lastFoundryWriteSnapshot(ctx, prior)
+		if (!snapshot) return json({ error: 'human_edit_pending', external_id: id }, 409)
+		const version = (snapshot.item as Record<string, unknown>).canonical_version
+		// Idempotent replay still requires the exact machine snapshot to be current.
+		if (prior.request_sha256 !== bodyHash && version !== body.expectedCanonicalVersion)
+			return json({ error: 'foundry_working_revision_changed', external_id: id }, 409)
+		if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1)
+			return json({ error: 'human_edit_pending', external_id: id }, 409)
+		expectedWorkingVersion = version
+	}
+	if (body.createOnly && prior && (prior.request_sha256 !== bodyHash || prior.status !== 'draft')) {
+		return json(
+			{ error: 'article_already_exists', external_id: id, content_id: prior.content_id },
+			409,
+		)
+	}
 	if (prior?.request_sha256 === bodyHash) {
 		console.info('[cms] foundry article request deduplicated', {
 			externalId: id,
@@ -610,8 +731,41 @@ async function putV2(
 	// Scheduled, review and archived items stay human-owned.
 	if (bound && !V2_WRITABLE.has(bound.status)) return approvalConflict(id, bound.status)
 
+	if (body.createOnly) {
+		if (body.expectedRevisionId) return json({ error: 'create_only_has_source_revision' }, 400)
+		if (body.adoptSourceId || bound)
+			return json({ error: 'article_already_exists', external_id: id }, 409)
+		const slugHolder = await findCandidate(ctx, 'slug', body.slug)
+		if (slugHolder) return slugConflict(id, body.slug, slugHolder.id)
+		const videoId = body.metadata?.videoId
+		if (typeof videoId !== 'string' || !/^[A-Za-z0-9_-]{11}$/.test(videoId))
+			return json({ error: 'create_only_requires_source_video' }, 400)
+		// Check the actual CMS working and immutable published projections, not
+		// just Foundry's own relationship ledger. A creation cannot adopt or edit.
+		const associated = await ctx.db
+			.prepare(`SELECT c.id FROM content_items c
+    LEFT JOIN content_revisions r ON r.id=c.published_revision_id AND r.content_id=c.id
+    WHERE c.type='article' AND c.deleted_at IS NULL AND (
+      CASE WHEN json_valid(c.metadata_json) THEN json_extract(c.metadata_json,'$.videoId') END = ?
+      OR CASE WHEN json_valid(json_extract(r.payload_json,'$.item.metadata_json')) THEN json_extract(json_extract(r.payload_json,'$.item.metadata_json'),'$.videoId') END = ?
+    ) LIMIT 1`)
+			.bind(videoId, videoId)
+			.first<{ id: string }>()
+		if (associated)
+			return json(
+				{ error: 'article_video_already_exists', external_id: id, content_id: associated.id },
+				409,
+			)
+	}
 	let adoption: Adoption | null = null
+	let expectedSourceVersion: number | undefined = expectedWorkingVersion
 	if (bound) {
+		if (body.expectedRevisionId) {
+			const version = await sourceRevisionVersion(ctx, bound.id, body.expectedRevisionId)
+			if (version === null) return json({ error: 'human_edit_pending', external_id: id }, 409)
+			expectedSourceVersion = version
+		}
+
 		const holder = await findCandidate(ctx, 'slug', body.slug)
 		if (holder && holder.id !== bound.id) return slugConflict(id, body.slug, holder.id)
 	} else {
@@ -619,7 +773,12 @@ async function putV2(
 		if ('error' in resolved) return resolved.error
 		if (resolved.candidate && resolved.matchedBy) {
 			const candidate = resolved.candidate
-			if (!(await bindAdoption(ctx, config, id, candidate))) {
+			if (body.expectedRevisionId) {
+				const version = await sourceRevisionVersion(ctx, candidate.id, body.expectedRevisionId)
+				if (version === null) return json({ error: 'human_edit_pending', external_id: id }, 409)
+				expectedSourceVersion = version
+			}
+			if (!(await bindAdoption(ctx, config, id, candidate, expectedSourceVersion))) {
 				return json(
 					{
 						error: 'adoption_conflict',
@@ -656,11 +815,44 @@ async function putV2(
 		}
 	}
 
-	// The canonical version Foundry's write must produce is one over this.
-	const priorVersion = bound ? await canonicalVersion(ctx, bound.id) : null
+	// Preserve a newer human working copy before PUT, not merely at publication.
+	// The native update pins this same canonical version in its atomic batch.
+	if (body.expectedRevisionId && !bound)
+		return json({ error: 'source_revision_missing', external_id: id }, 409)
+	const priorVersion =
+		expectedSourceVersion ?? (bound ? await canonicalVersion(ctx, bound.id) : null)
 	const heroImageId = body.hero_image_url
 		? await heroAssetId(body.hero_image_url)
 		: (body.hero_image_key ?? undefined)
+	// A pinned improvement augments its exact source metadata. Existing dates,
+	// image provenance and other recorded fields survive preparation updates.
+	let metadata = body.metadata
+	if (
+		(body.expectedRevisionId || body.expectedRequestSHA256) &&
+		body.metadata !== undefined &&
+		bound
+	) {
+		const source = body.expectedRevisionId
+			? (await getRevision(ctx.db, bound.id, body.expectedRevisionId))?.payload
+			: prior
+				? await lastFoundryWriteSnapshot(ctx, prior)
+				: null
+		let original: unknown
+		try {
+			original = JSON.parse(
+				String((source?.item as Record<string, unknown> | undefined)?.metadata_json ?? '{}'),
+			)
+		} catch {
+			return json({ error: 'source_metadata_invalid', external_id: id }, 409)
+		}
+		const recorded = ContentMetadataSchema.safeParse(original)
+		if (!recorded.success) return json({ error: 'source_metadata_invalid', external_id: id }, 409)
+		const merged = ContentMetadataSchema.safeParse(
+			mergePinnedArticleMetadata(recorded.data, body.metadata),
+		)
+		if (!merged.success) return json({ error: 'source_metadata_invalid', external_id: id }, 409)
+		metadata = merged.data
+	}
 	const nativeBody = {
 		title: body.title,
 		slug: body.slug,
@@ -672,7 +864,7 @@ async function putV2(
 		...(body.desk !== undefined ? { primaryCategory: body.desk } : {}),
 		...(body.tags !== undefined ? { tags: body.tags } : {}),
 		...(body.visibility !== undefined ? { visibility: body.visibility } : {}),
-		...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+		...(metadata !== undefined ? { metadata } : {}),
 		content: { bodyMarkdown: body.body_html, bodyHtml: body.body_html },
 	}
 
@@ -681,7 +873,12 @@ async function putV2(
 		// Each write is a CAS on the status it was read in: a draft stays a
 		// draft write, and a published item is edited in place only while it is
 		// still published (its live revision changes only on POST /publish).
-		const writer = bound.status === 'published' ? handlers.published : handlers.draft
+		if (priorVersion === null) return json({ error: 'human_edit_pending', external_id: id }, 409)
+		const writer = createContentRoutes({
+			...machineConfig(config),
+			updateStatusConstraint: bound.status,
+			updateCanonicalVersionConstraint: priorVersion,
+		})
 		nativeResponse = await mapUpdateConflict(
 			await writer.update(nativeContext(ctx, 'PATCH', nativeBody, { id: bound.id })),
 			id,
@@ -698,6 +895,8 @@ async function putV2(
 			)
 		} catch (error) {
 			const raced = await findContentBySource(ctx, id)
+			if (body.createOnly && raced)
+				return json({ error: 'article_already_exists', external_id: id, content_id: raced.id }, 409)
 			if (raced?.type !== 'article') throw error
 			nativeResponse = await mapUpdateConflict(
 				await handlers.draft.update(nativeContext(ctx, 'PATCH', nativeBody, { id: raced.id })),
@@ -1028,6 +1227,13 @@ export function createFoundryPublishRoutes(
 			if ('error' in auth) return auth.error
 			const row = await findArticle(ctx, id)
 			if (!row) return json({ error: 'not_found' }, 404)
+			const working = new URL(ctx.request.url).searchParams.get('working')
+			if (working !== null) {
+				if (working !== '1') return json({ error: 'invalid_working_source_request' }, 400)
+				if (!autoPublishEnabled(config))
+					return json({ error: 'native_working_source_unavailable' }, 409)
+				return workingArticleSource(ctx, row)
+			}
 			console.info('[cms] foundry article read', { externalId: id, receiptId: row.receipt_id })
 			if (autoPublishEnabled(config)) return json(v2Receipt(row))
 			return json(receipt(row))

package/src/routes/fronts-publish.ts

@@ -60,7 +60,10 @@ import { json, type RouteContext } from './context.js'
 // family rather than inventing a second one.
 export async function resolveFoundryHmacSecret(
 	env: Record<string, unknown> | undefined,
-	binding: 'FOUNDRY_HMAC_SECRET' | 'CMS_FOUNDRY_HMAC_SECRET' = 'FOUNDRY_HMAC_SECRET',
+	binding:
+		| 'FOUNDRY_HMAC_SECRET'
+		| 'CMS_FOUNDRY_HMAC_SECRET'
+		| 'INSIGHTS_INGEST_HMAC_SECRET' = 'FOUNDRY_HMAC_SECRET',
 ): Promise<string | null> {
 	const raw = env?.[binding]
 	if (typeof raw === 'string') return raw || null

package/src/routes/media-lib.ts

@@ -9,6 +9,7 @@
 // The `media.fronts.co/cdn-cgi/image` transform doc-comment + editorial-max
 // constants are theme-token — kept here as documentation only.
 
+import { z } from 'zod'
 import type { D1Database } from '../engine/d1.js'
 import { slugify } from '../engine/slug.js'
 
@@ -18,6 +19,23 @@ import { slugify } from '../engine/slug.js'
 
 const MEDIA_DOMAIN_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i
 
+/** Resolve the selected ready image; a legacy key or unavailable asset stays unknown. */
+export async function readReadyImagePublicUrl(db: D1Database, id: unknown): Promise<string | null> {
+	if (typeof id !== 'string' || id === '') return null
+	const asset = await db
+		.prepare(
+			"SELECT public_url FROM media_assets WHERE id = ? AND asset_type = 'image' AND status = 'ready'",
+		)
+		.bind(id)
+		.first<{ public_url: string | null }>()
+	const url = z.string().url().safeParse(asset?.public_url)
+	if (!url.success) return null
+	const parsed = new URL(url.data)
+	return parsed.protocol === 'https:' && !parsed.username && !parsed.password && !parsed.hash
+		? url.data
+		: null
+}
+
 /**
  * Resolve the public media domain, preferring `env.MEDIA_PUBLIC_DOMAIN` when it
  * looks like a valid host, else the site-configured default. Allows

package/src/ui/editor/ContentForm.tsx

@@ -33,7 +33,7 @@ import {
 	applyMediaSourceReadiness,
 	buildContentCreatePayload,
 	buildContentUpdatePayload,
-	canCreateContentDraft,
+	contentDraftSaveError,
 	foundryDispatchSourceForDraft,
 	initialContentMetadata,
 	type MediaSourceReadinessPayload,
@@ -406,19 +406,14 @@ export function ContentForm({
 			const draft = currentForm
 
 			if (id === null) {
-				if (
-					!canCreateContentDraft(contentType, draft, {
-						requirePrimaryTopic: primaryTopicEnabled,
-					})
-				) {
-					const mediaSource = foundryDispatchSourceForDraft(contentType, draft)
-					const missingMediaDuration =
-						mediaSource && normalizeMediaDurationSeconds(draft.durationSeconds) === null
+				const saveError = contentDraftSaveError(contentType, draft, {
+					requirePrimaryTopic: primaryTopicEnabled,
+					primaryTopicLabel: primaryTopic?.label,
+				})
+				if (saveError) {
 					setForm((prev) => ({
 						...prev,
-						saveError: missingMediaDuration
-							? 'Enter the authoritative media duration in whole seconds before saving.'
-							: 'Add the required title and content before saving.',
+						saveError,
 					}))
 					return
 				}
@@ -543,7 +538,7 @@ export function ContentForm({
 				}
 			}
 		},
-		[contentType, onDocCreated, primaryTopicEnabled, queueFoundryProcessing],
+		[contentType, onDocCreated, primaryTopicEnabled, primaryTopic?.label, queueFoundryProcessing],
 	)
 
 	useEffect(() => {

package/src/ui/editor/content-payload.ts

@@ -156,6 +156,23 @@ export function foundryDispatchSourceForDraft(
 	return null
 }
 
+/** Explain the same prerequisites that gate the first save, using the host's field label. */
+export function contentDraftSaveError(
+	contentType: ContentType,
+	draft: ContentDraftFields,
+	requirements: { requirePrimaryTopic?: boolean; primaryTopicLabel?: string } = {},
+): string | null {
+	if (canCreateContentDraft(contentType, draft, requirements)) return null
+	if (requirements.requirePrimaryTopic && !draft.primaryTopic?.trim()) {
+		return `Select ${requirements.primaryTopicLabel || 'a primary topic'} before saving.`
+	}
+	const mediaSource = foundryDispatchSourceForDraft(contentType, draft)
+	if (mediaSource && normalizeMediaDurationSeconds(draft.durationSeconds) === null) {
+		return 'Enter the authoritative media duration in whole seconds before saving.'
+	}
+	return 'Add the required title and content before saving.'
+}
+
 export function inferVideoSourceKind(sourceUrl: string): 'dropbox' | 'http_url' {
 	try {
 		const { hostname } = new URL(sourceUrl)