@growth-labs/cms 0.8.35 → 0.8.40

package/src/routes/content-insights.ts

@@ -25,6 +25,7 @@ import {
 	resolveFoundryHmacSecret as resolveFoundryHmacSecretForInputs,
 	verifyFoundrySignedRequest,
 } from './fronts-publish.js'
+import { readReadyImagePublicUrl } from './media-lib.js'
 
 const DismissSchema = z
 	.object({
@@ -67,6 +68,10 @@ const PublishedArticleSourceSchema = z
 		site: z.string().min(1),
 		observed_at: z.string().datetime(),
 		article: PublishedArticleStateSchema.extend({
+			publication_receipt_identity: z
+				.string()
+				.regex(/^[a-f0-9]{64}$/)
+				.nullable(),
 			hero_image_url: z.string().url().nullable(),
 			body_markdown: z.string().min(1).max(1_000_000),
 			description: z.string().nullable(),
@@ -111,17 +116,8 @@ async function publishedInputs(ctx: RouteContext, url: URL, siteId: string): Pro
 			if (!content || content.type !== 'article')
 				return json({ error: 'published_article_missing' }, 404)
 			const item = content.payload.item
-			let heroImageUrl: string | null = null
-			if (item.hero_image_id) {
-				const asset = await ctx.db
-					.prepare(
-						"SELECT public_url FROM media_assets WHERE id = ? AND asset_type = 'image' AND status = 'ready'",
-					)
-					.bind(item.hero_image_id)
-					.first<{ public_url: string | null }>()
-				const publicUrl = z.string().url().safeParse(asset?.public_url)
-				if (publicUrl.success) heroImageUrl = publicUrl.data
-			}
+			const snapshot = content.payload as unknown as Record<string, unknown>
+			const heroImageUrl = await readReadyImagePublicUrl(ctx.db, item.hero_image_id)
 			const result = PublishedArticleSourceSchema.safeParse({
 				ok: true,
 				schema: 'cms.published-article-source.v1',
@@ -130,6 +126,7 @@ async function publishedInputs(ctx: RouteContext, url: URL, siteId: string): Pro
 				article: {
 					content_id: content.contentId,
 					revision_id: content.revisionId,
+					publication_receipt_identity: snapshot.publication_receipt_identity ?? null,
 					slug: content.slug,
 					title: item.title,
 					canonical_url: item.canonical_url ?? null,
@@ -215,7 +212,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)
@@ -224,21 +221,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 {
@@ -355,7 +344,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

@@ -35,6 +35,7 @@ import {
 	setFrontsChannelTargets,
 } from '../engine/fronts-publish-intent.js'
 import { classifyGoogleDriveUrl } from '../engine/google-drive-source.js'
+import type { NativeArticleDraftSnapshot } from '../engine/publication-current-guard.js'
 import { evaluateArticleBody } from '../engine/publish-guard.js'
 import {
 	createContent,
@@ -237,6 +238,8 @@ export interface ContentRouteConfig extends CmsRouteConfig {
 	updateStatusConstraint?: ContentStatus
 	/** Internal machine-route pin; joins the existing status-constrained atomic batch. */
 	updateCanonicalVersionConstraint?: number
+	/** Exact native draft input; joins the status/version constrained batch. */
+	updateNativeDraftSnapshotConstraint?: NativeArticleDraftSnapshot
 	/**
 	 * Internal (Foundry machine route, M3-18): replaces ONLY the publish action's
 	 * commit step (publishContent + createRevision) with the caller's — publishOne
@@ -1810,6 +1813,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				updated = await updateContentItem(ctx.db, id, parsed.data, {
 					requiredStatus: config.updateStatusConstraint,
 					expectedCanonicalVersion: config.updateCanonicalVersionConstraint,
+					expectedNativeDraftSnapshot: config.updateNativeDraftSnapshotConstraint,
 					...(expectedMediaSource ? { expectedMediaSource } : {}),
 				})
 			} catch (error) {

package/src/routes/foundry-publish.ts

@@ -2,15 +2,22 @@ import { isCanonicalHost, sha256Hex, verifyFoundryRequest } from '@growth-labs/f
 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'
+import {
+	type NativeArticleDraftSnapshot,
+	PublicationCurrentSnapshotError,
+} from '../engine/publication-current-guard.js'
+import {
+	canonicalJsonSha256,
+	type JsonValue,
+} from '../engine/publication-receipt/canonical-json.js'
+import { getContentSnapshot, PublishContentValidationError } from '../engine/publisher.js'
 import { createRevisionWithDelta, getRevision } from '../engine/revisions.js'
 import { buildContentPath, slugify } from '../engine/slug.js'
 import { type FoundryArticleV2, FoundryArticleV2Schema } from '../foundry-emit.js'
 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, readyImagePublicUrl } from './media-lib.js'
 
 const SOURCE_PREFIX = 'foundry:'
 
@@ -118,7 +125,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,
@@ -605,6 +615,147 @@ 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 projection = await projectArticleSource(ctx, row, snapshot)
+	if (projection instanceof Response) return projection
+	return json({ ...v2Receipt(row), working: projection })
+}
+
+async function projectArticleSource(
+	ctx: RouteContext,
+	row: FoundryArticleRow,
+	snapshot: Record<string, unknown>,
+): Promise<z.infer<typeof WorkingArticleSourceSchema> | Response> {
+	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: Object.hasOwn(snapshot, 'hero_asset')
+			? readyImagePublicUrl(snapshot.hero_asset as Record<string, unknown> | null)
+			: 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 result.data
+}
+
+/** Current input for governed preparation, never evidence of an earlier PUT. */
+async function draftPreparationSnapshot(
+	ctx: RouteContext,
+	row: FoundryArticleRow,
+): Promise<Record<string, unknown> | null> {
+	if (row.status !== 'draft') return null
+	const snapshot = await getContentSnapshot(ctx.db, row.content_id)
+	const item = snapshot?.item as Record<string, unknown> | undefined
+	if (
+		!(
+			snapshot &&
+			item?.id === row.content_id &&
+			item.type === 'article' &&
+			item.status === 'draft' &&
+			item.deleted_at == null &&
+			item.source_id === `${SOURCE_PREFIX}${row.external_id}` &&
+			typeof item.canonical_version === 'number' &&
+			Number.isSafeInteger(item.canonical_version) &&
+			item.canonical_version > 0
+		)
+	)
+		return null
+	const hero =
+		typeof item.hero_image_id === 'string'
+			? await ctx.db
+					.prepare('SELECT * FROM media_assets WHERE id=? LIMIT 1')
+					.bind(item.hero_image_id)
+					.first<Record<string, unknown>>()
+			: null
+	return { ...snapshot, hero_asset: hero }
+}
+
+async function draftPreparationSource(
+	ctx: RouteContext,
+	row: FoundryArticleRow,
+): Promise<Response> {
+	const snapshot = await draftPreparationSnapshot(ctx, row)
+	if (!snapshot) return json({ error: 'draft_preparation_source_unavailable' }, 409)
+	const projection = await projectArticleSource(ctx, row, snapshot)
+	if (projection instanceof Response) return projection
+	return json({
+		...v2Receipt(row),
+		draft_preparation: {
+			...projection,
+			schema: 'cms.foundry-draft-preparation.v1',
+			source_id: `${SOURCE_PREFIX}${row.external_id}`,
+			snapshot_sha256: await canonicalJsonSha256(
+				nativeDraftInput(snapshot, row) as unknown as JsonValue,
+			),
+		},
+	})
+}
+
+function nativeDraftInput(
+	snapshot: Record<string, unknown>,
+	row: FoundryArticleRow,
+): NativeArticleDraftSnapshot {
+	return {
+		snapshot,
+		binding: {
+			externalId: row.external_id,
+			contentId: row.content_id,
+			receiptId: row.receipt_id,
+			requestSHA256: row.request_sha256,
+		},
+	}
+}
+
 /** 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'>,
@@ -629,6 +780,51 @@ async function putV2(
 	const body = parsed.data
 
 	const prior = await findArticle(ctx, id)
+	let expectedWorkingVersion: number | undefined
+	let preparedDraftSnapshot: Record<string, unknown> | null = null
+	if (body.expectedDraftSnapshot) {
+		const pin = body.expectedDraftSnapshot
+		// A replay is read-only and still requires this exact PUT's snapshot.
+		if (prior?.request_sha256 === bodyHash) {
+			if (!(await lastFoundryWriteSnapshot(ctx, prior)))
+				return json({ error: 'foundry_working_revision_changed', external_id: id }, 409)
+			return json(v2Receipt(prior))
+		}
+		if (
+			!prior ||
+			prior.content_id !== pin.contentId ||
+			prior.request_sha256 !== pin.priorRequestSHA256
+		)
+			return json({ error: 'draft_preparation_source_changed', external_id: id }, 409)
+		preparedDraftSnapshot = await draftPreparationSnapshot(ctx, prior)
+		const item = preparedDraftSnapshot?.item as Record<string, unknown> | undefined
+		if (
+			!preparedDraftSnapshot ||
+			item?.canonical_version !== pin.canonicalVersion ||
+			item?.slug !== body.slug ||
+			(await canonicalJsonSha256(
+				nativeDraftInput(preparedDraftSnapshot, prior) as unknown as JsonValue,
+			)) !== pin.sha256
+		)
+			return json({ error: 'draft_preparation_source_changed', external_id: id }, 409)
+		expectedWorkingVersion = pin.canonicalVersion
+	}
+	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 },
@@ -677,7 +873,7 @@ async function putV2(
 			)
 	}
 	let adoption: Adoption | null = null
-	let expectedSourceVersion: number | undefined
+	let expectedSourceVersion: number | undefined = expectedWorkingVersion
 	if (bound) {
 		if (body.expectedRevisionId) {
 			const version = await sourceRevisionVersion(ctx, bound.id, body.expectedRevisionId)
@@ -746,11 +942,23 @@ async function putV2(
 	// 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.metadata !== undefined && bound) {
-		const source = await getRevision(ctx.db, bound.id, body.expectedRevisionId)
+	if (
+		(body.expectedRevisionId || body.expectedRequestSHA256 || body.expectedDraftSnapshot) &&
+		body.metadata !== undefined &&
+		bound
+	) {
+		const source =
+			preparedDraftSnapshot ??
+			(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?.payload.item?.metadata_json ?? '{}'))
+			original = JSON.parse(
+				String((source?.item as Record<string, unknown> | undefined)?.metadata_json ?? '{}'),
+			)
 		} catch {
 			return json({ error: 'source_metadata_invalid', external_id: id }, 409)
 		}
@@ -787,6 +995,9 @@ async function putV2(
 			...machineConfig(config),
 			updateStatusConstraint: bound.status,
 			updateCanonicalVersionConstraint: priorVersion,
+			...(preparedDraftSnapshot && prior
+				? { updateNativeDraftSnapshotConstraint: nativeDraftInput(preparedDraftSnapshot, prior) }
+				: {}),
 		})
 		nativeResponse = await mapUpdateConflict(
 			await writer.update(nativeContext(ctx, 'PATCH', nativeBody, { id: bound.id })),
@@ -1136,6 +1347,15 @@ 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' && working !== 'prepare')
+					return json({ error: 'invalid_working_source_request' }, 400)
+				if (!autoPublishEnabled(config))
+					return json({ error: 'native_working_source_unavailable' }, 409)
+				if (working === 'prepare') return draftPreparationSource(ctx, row)
+				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

@@ -30,6 +30,7 @@ import {
 	applyFrontsPublishCallback,
 	isFrontsPublishEnabled,
 	listFrontsPublishSchedule,
+	readFrontsPublishObservation,
 } from '../engine/fronts-publish.js'
 import {
 	backfillFrontsChannelTargets,
@@ -60,7 +61,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
@@ -222,6 +226,8 @@ async function runScheduleMaintenance(
 }
 
 export interface FrontsPublishRouteHandlers {
+	/** GET /fronts/publish-callback — exact authenticated receiver/commit observation. */
+	readPublishCallback(ctx: RouteContext): Promise<Response>
 	/** GET /fronts/schedule?window=<from>..<to> — items due for foundryd to publish. */
 	schedule(ctx: RouteContext): Promise<Response>
 	/** POST /fronts/schedule — bounded target arming or host-owned maintenance. */
@@ -257,6 +263,60 @@ function parseWindow(
 export function createFrontsPublishRoutes(config: ContentRouteConfig): FrontsPublishRouteHandlers {
 	const resolved = resolveConfig(config)
 	return {
+		async readPublishCallback(ctx) {
+			const secret = await resolveFoundryHmacSecret(ctx.env)
+			if (!secret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+			const url = new URL(ctx.request.url)
+			const payload = `foundry.fronts-publish-observation.v1\nGET\n${url.pathname}\n${url.search}`
+			const denied = await verifyFoundrySignedRequest(
+				ctx.request,
+				secret,
+				payload,
+				'fronts/publish-callback.read',
+			)
+			if (denied) return denied
+			if (ctx.request.method !== 'GET') return json({ error: 'method_not_allowed' }, 405)
+			const keys = [
+				'event_id',
+				'intent_id',
+				'content_id',
+				'version',
+				'publish_at',
+				'status',
+				'receipt_sha256',
+			]
+			if (
+				[...url.searchParams.keys()].some((key) => !keys.includes(key)) ||
+				keys.some((key) => url.searchParams.getAll(key).length !== 1)
+			)
+				return json({ error: 'invalid_observation_binding' }, 400)
+			const values = Object.fromEntries(url.searchParams)
+			if (
+				['event_id', 'intent_id', 'content_id'].some(
+					(key) => !values[key] || values[key]!.length > 200,
+				) ||
+				!/^\d+$/.test(values.version!) ||
+				!Number.isSafeInteger(Number(values.version)) ||
+				Number(values.version) < 1 ||
+				!/^\d+$/.test(values.publish_at!) ||
+				!Number.isSafeInteger(Number(values.publish_at)) ||
+				!['publishing', 'live'].includes(values.status!) ||
+				(values.status === 'live'
+					? !/^[0-9a-f]{64}$/.test(values.receipt_sha256!)
+					: values.receipt_sha256 !== '')
+			)
+				return json({ error: 'invalid_observation_binding' }, 400)
+			const result = await readFrontsPublishObservation(ctx.db, {
+				eventId: values.event_id!,
+				intentId: values.intent_id!,
+				contentId: values.content_id!,
+				version: Number(values.version),
+				publishAt: Number(values.publish_at),
+				status: values.status as 'publishing' | 'live',
+				receiptSHA256: values.receipt_sha256!,
+			})
+			return json(result, result.state === 'conflict' ? 409 : 200)
+		},
 		async maintainSchedule(ctx) {
 			let responseOperation: 'arm-channel-targets' | FrontsScheduleMaintenanceOperation =
 				'arm-channel-targets'

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,29 @@ 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 }>()
+	return readyImagePublicUrl(asset ? { ...asset, asset_type: 'image', status: 'ready' } : null)
+}
+
+/** The same projection from an already captured asset row. */
+export function readyImagePublicUrl(asset: Record<string, unknown> | null): string | null {
+	if (!asset || asset.asset_type !== 'image' || asset.status !== 'ready') return 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/api/fronts/publish-callback.ts

@@ -10,3 +10,6 @@ import { toContentConfig, toContentCtx } from '../_content-config.js'
 
 export const POST = (c: APIContext) =>
 	createFrontsPublishRoutes(toContentConfig(c)).publishCallback(toContentCtx(c, {}))
+
+export const GET = (c: APIContext) =>
+	createFrontsPublishRoutes(toContentConfig(c)).readPublishCallback(toContentCtx(c, {}))

package/src/ui/editor/extensions.ts

@@ -1,13 +1,27 @@
 import { DragHandle } from '@tiptap/extension-drag-handle'
+import Heading from '@tiptap/extension-heading'
 import Image from '@tiptap/extension-image'
 import Link from '@tiptap/extension-link'
 import { TableKit } from '@tiptap/extension-table'
 import StarterKit from '@tiptap/starter-kit'
 import { Callout, Citation, GeneratedFaq, PullQuote } from './blocks.js'
+import { BODY_HEADING_LEVELS, bodyHeadingLevel } from './heading-level.js'
 import { SlashMenu } from './slash-menu.js'
 import { TrimBoundaryMarks } from './trim-boundary-marks.js'
 import { TweetEmbed } from './tweet-embed.js'
 
+/** StarterKit's heading restricted to the body levels. Every pasted h1–h6
+ * parses onto the nearest body level instead of dropping to a paragraph, so a
+ * document's Heading 1 chapter titles arrive as H2. */
+const BodyHeading = Heading.extend({
+	parseHTML() {
+		return [1, 2, 3, 4, 5, 6].map((level) => ({
+			tag: `h${level}`,
+			attrs: { level: bodyHeadingLevel(level) },
+		}))
+	},
+}).configure({ levels: [...BODY_HEADING_LEVELS] })
+
 function renderDragHandle(): HTMLElement {
 	const handle = document.createElement('div')
 	handle.className = 'drag-handle'
@@ -25,7 +39,8 @@ function renderDragHandle(): HTMLElement {
  * silently drops underline styling on paste — Word documents come in clean. */
 export function createRteExtensions() {
 	return [
-		StarterKit.configure({ link: false, underline: false }),
+		StarterKit.configure({ link: false, underline: false, heading: false }),
+		BodyHeading,
 		Link.configure({ openOnClick: false }),
 		TrimBoundaryMarks,
 		Image,

package/src/ui/editor/heading-level.ts

@@ -0,0 +1,14 @@
+// src/ui/editor/heading-level.ts — PURE (no Tiptap import; serializers use it).
+// Body heading levels. The page title is the article's only H1, so a body
+// Heading 1 (typed as `# ` or pasted from a document) is a chapter title and
+// becomes an H2; h5/h6 fold into H4, the deepest level the public prose styles.
+
+export const BODY_HEADING_LEVELS = [2, 3, 4] as const
+
+export type BodyHeadingLevel = (typeof BODY_HEADING_LEVELS)[number]
+
+export function bodyHeadingLevel(level: number): BodyHeadingLevel {
+	if (!Number.isFinite(level) || level <= 2) return 2
+	if (level >= 4) return 4
+	return 3
+}

package/src/ui/editor/portable-text.ts

@@ -20,6 +20,7 @@
 import type { JSONContent } from '@tiptap/core'
 import type { PortableTextObject } from '../../schema/portable-text.js'
 import { normalizeBoundaryMarks } from './boundary-marks.js'
+import { bodyHeadingLevel } from './heading-level.js'
 
 type KeyGenerator = () => string
 
@@ -78,7 +79,7 @@ function serializeBlockNode(
 			out.push(buildTextBlock('normal', node.content ?? [], nextKey, list))
 			return
 		case 'heading': {
-			const level = (node.attrs?.level as number) ?? 2
+			const level = bodyHeadingLevel((node.attrs?.level as number) ?? 2)
 			out.push(buildTextBlock(`h${level}`, node.content ?? [], nextKey, list))
 			return
 		}
@@ -407,7 +408,7 @@ function parseObject(block: PortableTextObject): JSONContent {
 			if (heading) {
 				return {
 					type: 'heading',
-					attrs: { level: Number(heading[1]) },
+					attrs: { level: bodyHeadingLevel(Number(heading[1])) },
 					content: parseInline(block),
 				}
 			}

package/src/ui/editor/serialize.ts

@@ -4,7 +4,7 @@
 // no EditorView, no DOM, fully testable in vitest (Node env).
 //
 // Supported nodes (StarterKit set + TweetEmbed + tables):
-//   block: doc, paragraph, heading (h1–h6), bulletList, orderedList,
+//   block: doc, paragraph, heading (h2–h4; h1 → h2, h5/h6 → h4), bulletList, orderedList,
 //          listItem, blockquote, codeBlock, image, tweetEmbed, hardBreak,
 //          table (tableRow / tableHeader / tableCell)
 //   inline marks: bold, italic, strike, code, link
@@ -30,6 +30,7 @@
 
 import type { JSONContent } from '@tiptap/core'
 import { normalizeBoundaryMarks } from './boundary-marks.js'
+import { bodyHeadingLevel } from './heading-level.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // docToMarkdown — JSONContent → string
@@ -52,7 +53,7 @@ function serializeBlock(node: JSONContent): string | null {
 			return text
 		}
 		case 'heading': {
-			const level = (node.attrs?.level as number) ?? 2
+			const level = bodyHeadingLevel((node.attrs?.level as number) ?? 2)
 			const prefix = '#'.repeat(level)
 			const text = serializeInlineContent(node.content ?? [])
 			return `${prefix} ${text}`
@@ -389,7 +390,7 @@ function parseBlocks(md: string): JSONContent[] {
 		// Heading
 		const headingMatch = /^(#{1,6})\s+(.*)$/.exec(line)
 		if (headingMatch) {
-			const level = headingMatch[1].length
+			const level = bodyHeadingLevel(headingMatch[1].length)
 			const text = headingMatch[2].trim()
 			nodes.push({ type: 'heading', attrs: { level }, content: parseInline(text) })
 			i++