@growth-labs/cms 0.5.29 → 0.5.31

package/src/engine/validator/checks/source-section-diagnostics.ts

@@ -0,0 +1,187 @@
+/**
+ * Source-section diagnostics (#329).
+ *
+ * These run against markdown that has ALREADY been through
+ * `normalizeSourceSections()`. That ordering is the whole point: the
+ * normalizer fixes everything mechanically fixable, so anything still present
+ * here needs an editor's judgement rather than another rewrite — and each of
+ * these is a proven render breaker, which is why they block publish.
+ *
+ * Draft autosave stays allowed regardless; an editor must never lose work to a
+ * formatting complaint.
+ */
+import { normalizeSourceSections } from '../../source-sections.js'
+import type {
+	ArticleBodyInput,
+	ValidationError,
+	ValidationErrorCode,
+	ValidationSpan,
+} from '../types.js'
+import { makeError } from '../types.js'
+
+export interface SourceSectionOptions {
+	/** Escalate these diagnostics from warn to block. Publish sets this. */
+	blockSourceSectionDefects?: boolean
+}
+
+const NBSP = ' '
+const MANUAL_BULLET = /^\s*[●•▪]/u
+const LINK = /\[([^\]]*)\]\(([^)]*)\)/g
+
+interface SectionLine {
+	text: string
+	/** Byte offset of this line in the source document. */
+	start: number
+}
+
+/** Lines inside every Sources/References section, with document offsets. */
+function collectSectionLines(source: string): SectionLine[] {
+	const lines = source.split('\n')
+	const collected: SectionLine[] = []
+	let offset = 0
+	let sectionLevel: number | null = null
+
+	for (const text of lines) {
+		const heading = /^(#{1,6})\s+(.*)$/.exec(text)
+		const level = heading ? (heading[1]?.length ?? 0) : null
+
+		if (sectionLevel !== null && level !== null && level <= sectionLevel) {
+			sectionLevel = null
+		}
+
+		if (sectionLevel !== null) {
+			collected.push({ text, start: offset })
+		} else if (level !== null) {
+			const word = (heading?.[2] ?? '')
+				.replace(/[*_]/g, '')
+				.replace(/\s*:\s*$/, '')
+				.trim()
+			if (/^(sources|references)$/i.test(word)) sectionLevel = level
+		}
+
+		offset += text.length + 1
+	}
+
+	return collected
+}
+
+function isFormattingOnly(text: string): boolean {
+	if (text.trim() === '') return false
+	return (
+		text
+			.replaceAll(NBSP, ' ')
+			.replace(/[*_~`#]/g, '')
+			.trim() === ''
+	)
+}
+
+/** Emphasis delimiters wrapping the entire label, e.g. `[**t**](u)`. */
+function hasWholeLabelEmphasis(label: string): boolean {
+	const match = /^(\*\*|__|\*|_)([\s\S]+)\1$/.exec(label.trim())
+	if (!match) return false
+	return !(match[2] ?? '').includes(match[1] as string)
+}
+
+/** An odd number of `**` or `*` runs — ambiguous, so the normalizer left it. */
+function hasUnbalancedEmphasis(label: string): boolean {
+	const strong = (label.match(/\*\*/g) ?? []).length
+	if (strong % 2 !== 0) return true
+	const em = (label.replace(/\*\*/g, '').match(/\*/g) ?? []).length
+	if (em % 2 !== 0) return true
+	const under = (label.match(/__/g) ?? []).length
+	return under % 2 !== 0
+}
+
+export function check(
+	input: ArticleBodyInput,
+	options: SourceSectionOptions = {},
+): ValidationError[] {
+	// Warn on save, block on publish. The design keeps draft autosave working
+	// so an editor cannot lose work to a formatting complaint, while still
+	// refusing to publish a section that is a proven render breaker.
+	const escalate = options.blockSourceSectionDefects === true
+	const report = (
+		code: ValidationErrorCode,
+		message: string,
+		span?: ValidationSpan,
+	): ValidationError => {
+		const error = makeError(code, message, span)
+		return escalate ? { ...error, severity: 'block' } : error
+	}
+
+	if (!input.body_markdown) return []
+
+	// Report against normalized text so a defect the normalizer would have
+	// fixed is never surfaced to the editor as their problem.
+	const source = normalizeSourceSections(input.body_markdown).markdown
+	const errors: ValidationError[] = []
+	const lines = collectSectionLines(source)
+
+	let linkLike = 0
+	let listItems = 0
+
+	for (const { text, start } of lines) {
+		const span = { start, end: start + text.length }
+
+		if (MANUAL_BULLET.test(text)) {
+			errors.push(
+				report(
+					'source-section-manual-bullet',
+					`This source line still starts with a manual bullet character. Replace it with "- " so it renders as one list, not separate paragraphs.`,
+					span,
+				),
+			)
+		}
+
+		if (isFormattingOnly(text)) {
+			errors.push(
+				report(
+					'source-section-formatting-only-line',
+					`This line contains only formatting characters and renders as an empty heading. Delete it.`,
+					span,
+				),
+			)
+		}
+
+		if (/^\s*[-*+]\s+/.test(text)) listItems++
+
+		for (const link of text.matchAll(LINK)) {
+			const label = link[1] ?? ''
+			if (label.trim() !== '') linkLike++
+
+			if (hasWholeLabelEmphasis(label)) {
+				errors.push(
+					report(
+						'source-section-wrapped-link-label',
+						`The link title "${label.trim()}" is wrapped in emphasis markers, which stay visible inside the link. Remove the surrounding * or _ characters.`,
+						span,
+					),
+				)
+			} else if (hasUnbalancedEmphasis(label)) {
+				errors.push(
+					report(
+						'source-section-unbalanced-emphasis',
+						`The link title "${label.trim()}" has an unmatched emphasis marker. Close it or remove it — it cannot be corrected automatically without changing the title.`,
+						span,
+					),
+				)
+			}
+		}
+	}
+
+	// A section that reads as a list of sources but has no list items at all
+	// renders as a run of paragraphs. Only claim this when there is something
+	// list-shaped to talk about.
+	if (listItems === 0 && linkLike > 1) {
+		const first = lines[0]
+		errors.push(
+			report(
+				'source-section-unlistable',
+				`This source section has ${linkLike} links but no list items, so it renders as separate paragraphs. Start each source line with "- ".`,
+				first ? { start: first.start, end: first.start + first.text.length } : undefined,
+			),
+		)
+	}
+
+	return errors
+}

package/src/engine/validator/index.ts

@@ -21,6 +21,7 @@ import * as iframeMissingDims from './checks/iframe-missing-dims-and-wrapper.js'
 import * as invisibleControl from './checks/invisible-control-chars.js'
 import * as paywallMarker from './checks/paywall-marker-leak.js'
 import * as rawBlockHtml from './checks/raw-block-html.js'
+import * as sourceSectionDiagnostics from './checks/source-section-diagnostics.js'
 import * as unresolvedAnchor from './checks/unresolved-footnote-anchor.js'
 import * as wordGdocs from './checks/word-gdocs-paste-artifacts.js'
 
@@ -302,6 +303,7 @@ export const checkBareUrlNotAutolinked = bareUrl.check
 export const checkEmptyAltText = emptyAlt.check
 export const checkIframeMissingDimsAndWrapper = iframeMissingDims.check
 export const checkHeadingHierarchySkip = headingHierarchy.check
+export const checkSourceSectionDiagnostics = sourceSectionDiagnostics.check
 export const checkPaywallMarkerLeak = paywallMarker.check
 
 /* -------------------------------------------------------------------------- */
@@ -310,11 +312,20 @@ export const checkPaywallMarkerLeak = paywallMarker.check
 
 export interface RunOptions extends ValidatorOptions {
 	requireBody: boolean
+	/**
+	 * Escalate source-section diagnostics (#329) from warn to block.
+	 *
+	 * Defaults to false so a draft save is never rejected for formatting — the
+	 * PATCH route returns 422 on any block-severity error. Publish call sites
+	 * set it to true, which is where the design wants these enforced.
+	 */
+	blockSourceSectionDefects: boolean
 }
 
 export const DEFAULT_RUN_OPTIONS: RunOptions = {
 	...DEFAULT_OPTIONS,
 	requireBody: true,
+	blockSourceSectionDefects: false,
 }
 
 /**
@@ -349,6 +360,7 @@ export function validateArticleBody(
 	errors.push(...checkEmptyAltText(input))
 	errors.push(...checkIframeMissingDimsAndWrapper(input))
 	errors.push(...checkHeadingHierarchySkip(input))
+	errors.push(...checkSourceSectionDiagnostics(input, opts))
 	errors.push(...checkPaywallMarkerLeak(input))
 	// Heuristic.
 	errors.push(...checkUnbalancedMarkdownEmphasis(input))

package/src/engine/validator/types.ts

@@ -55,6 +55,15 @@ export type ValidationErrorCode =
 	| 'heading-hierarchy-skip'
 	| 'paywall-marker-leak'
 	| 'stale-body-html'
+	// Source-section diagnostics (#329). Reported only for defects that
+	// SURVIVE normalizeSourceSections() — the normalizer already fixed
+	// everything mechanically fixable, so what is left needs an editor's
+	// judgement. Warn on save, block on publish; see SEVERITY below.
+	| 'source-section-manual-bullet'
+	| 'source-section-formatting-only-line'
+	| 'source-section-wrapped-link-label'
+	| 'source-section-unbalanced-emphasis'
+	| 'source-section-unlistable'
 
 export type ValidationResult = { ok: true } | { ok: false; errors: ValidationError[] }
 
@@ -88,6 +97,16 @@ export const SEVERITY: Readonly<Record<ValidationErrorCode, Severity>> = {
 	'heading-hierarchy-skip': 'warn',
 	'paywall-marker-leak': 'block',
 	'stale-body-html': 'block',
+	// #329. WARN by default so a draft save is never rejected — the design is
+	// explicit that an editor must not lose work to a formatting complaint, and
+	// the PATCH route returns 422 on any block-severity error. Publish call
+	// sites pass `blockSourceSectionDefects` to escalate these to block, which
+	// is where the design wants them enforced.
+	'source-section-manual-bullet': 'warn',
+	'source-section-formatting-only-line': 'warn',
+	'source-section-wrapped-link-label': 'warn',
+	'source-section-unbalanced-emphasis': 'warn',
+	'source-section-unlistable': 'warn',
 }
 
 export interface ValidatorOptions {

package/src/integration/index.ts

@@ -102,6 +102,16 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					pattern: `${base}/api/content/insights-ingest`,
 					entrypoint: resolveEntrypoint('../ui/api/content/insights-ingest'),
 				})
+				// Fronts publish path (additive, flag-gated) — M2M siblings of the
+				// foundry-callback / insights-ingest routes. HMAC-guarded.
+				injectRoute({
+					pattern: `${base}/api/fronts/schedule`,
+					entrypoint: resolveEntrypoint('../ui/api/fronts/schedule'),
+				})
+				injectRoute({
+					pattern: `${base}/api/fronts/publish-callback`,
+					entrypoint: resolveEntrypoint('../ui/api/fronts/publish-callback'),
+				})
 				// Content list + create (Library screen)
 				injectRoute({
 					pattern: `${base}/api/content`,

package/src/providers/types.ts

@@ -430,7 +430,7 @@ export interface SettingsProvider {
 }
 
 export interface SurveyProvider {
-	getResults(input: { surveyId: string }): Promise<SurveyResults>
+	getResults(input: { surveyId: string; offset?: number }): Promise<SurveyResults>
 	getCsv(input: { surveyId: string }): Promise<SurveyCsvResult>
 }
 

package/src/routes/content.ts

@@ -56,6 +56,7 @@ import {
 } from '../engine/revisions.js'
 import { applySlugRenameRedirects } from '../engine/slug-redirects.js'
 import { softDeleteContent } from '../engine/soft-delete.js'
+import { normalizeSourceSections } from '../engine/source-sections.js'
 import { TagInputError } from '../engine/taxonomy.js'
 import type { ValidationError } from '../engine/validator/index.js'
 import { parseLayoutEnvelope } from '../schema/layout.js'
@@ -1258,9 +1259,29 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 						bodyMarkdown?: string
 						bodyHtml?: string | null
 					}
-					const bodyMarkdown = articleContent.bodyMarkdown
-					const bodyHtml = articleContent.bodyHtml
+					let bodyMarkdown = articleContent.bodyMarkdown
+					let bodyHtml = articleContent.bodyHtml
 					const isDraft = existing.status === 'draft'
+
+					// Safe, deterministic Sources/References cleanup is applied before
+					// the body is persisted, so the stored Markdown is canonical and the
+					// editor's next read shows what will actually render (#329).
+					//
+					// When normalization changes the Markdown, any body_html the client
+					// sent alongside it was rendered from the pre-normalization text and
+					// is stale by construction. Persisting it would let the exact defect
+					// this fixes survive in the rendered output, which is how the
+					// original incident reached a published page — so it is dropped and
+					// re-rendered downstream.
+					if (typeof bodyMarkdown === 'string') {
+						const normalized = normalizeSourceSections(bodyMarkdown)
+						if (normalized.changed) {
+							bodyMarkdown = normalized.markdown
+							bodyHtml = null
+							articleContent.bodyMarkdown = normalized.markdown
+							articleContent.bodyHtml = null
+						}
+					}
 					if (bodyMarkdown !== undefined || bodyHtml !== undefined) {
 						const guard = evaluateArticleBody(
 							{ body_markdown: bodyMarkdown ?? null, body_html: bodyHtml ?? null },

package/src/routes/fronts-publish.ts

@@ -0,0 +1,292 @@
+// Fronts publish routes (cms/Masthead side) — the two machine-to-machine seams
+// the out-of-process Fronts publish worker (foundryd) drives:
+//
+//   GET  /admin/api/fronts/schedule?window=<from>..<to>  — the poll surface.
+//   POST /admin/api/fronts/publish-callback              — the callback receiver.
+//
+// AUTH reuses the existing M2M primitive (`verifyHmac` + `X-Foundry-Signature`
+// against `ctx.env.FOUNDRY_HMAC_SECRET` — a per-Worker secret string OR a Secrets
+// Store binding `{ get() }`; no new auth scheme, no shared secret in code/D1),
+// hardened against replay with a REQUIRED `X-Foundry-Timestamp`:
+//
+//   X-Foundry-Timestamp: <unix seconds, within ±300s of now>
+//   X-Foundry-Signature: sha256=HMAC(secret, `${timestamp}\n${payload}`)
+//
+// where payload is the raw query string (`url.search`) for the GET poll and the
+// raw body for the POST callback. Binding the signature to a fresh timestamp
+// stops replay: without it a no-`window` GET would sign HMAC(secret,"") — a
+// CONSTANT — so one captured URL+header pair would be a permanent bearer
+// credential for the pre-publication embargo schedule.
+//
+// Both endpoints ship ENABLED behind FRONTS_PUBLISH_ENABLED (a rollback lever,
+// default ON). Failures are loud: bad/stale HMAC → 401 + warn log; a `live`
+// callback that cannot commit through the ledger → 500 + error log; disabled → 503.
+
+import { z } from 'zod'
+import { verifyHmac } from '../engine/foundry-dispatch.js'
+import {
+	applyFrontsPublishCallback,
+	isFrontsPublishEnabled,
+	listFrontsPublishSchedule,
+} from '../engine/fronts-publish.js'
+import { hydrateFrontsPublishIntents } from '../engine/fronts-publish-intent.js'
+import { publicUrlFor } from '../ui/screens/public-url.js'
+import { type CmsRouteConfig, resolveConfig } from './config.js'
+import { json, type RouteContext } from './context.js'
+
+/**
+ * Resolve the Foundry HMAC secret from ctx.env.FOUNDRY_HMAC_SECRET — the SAME
+ * binding the existing foundry-callback route uses. Supports a plain string
+ * (test injection / per-Worker secret) or a Secrets Store binding `{ get() }`.
+ * Returns null → the route answers 500 "not configured".
+ */
+async function resolveFoundryHmacSecret(
+	env: Record<string, unknown> | undefined,
+): Promise<string | null> {
+	const raw = env?.FOUNDRY_HMAC_SECRET
+	if (typeof raw === 'string') return raw || null
+	if (raw && typeof (raw as { get?: unknown }).get === 'function') {
+		try {
+			const val = await (raw as { get(): Promise<string> }).get()
+			return typeof val === 'string' && val.length > 0 ? val : null
+		} catch {
+			return null
+		}
+	}
+	return null
+}
+
+/** Max clock skew (seconds) tolerated on X-Foundry-Timestamp — the replay window. */
+const SIGNATURE_MAX_SKEW_SECONDS = 300
+
+/** Parse the X-Foundry-Timestamp header (strict unix epoch seconds) or null. */
+function parseTimestampSeconds(raw: string): number | null {
+	const trimmed = raw.trim()
+	// Strict integer seconds so the exact header bytes are what foundryd signs.
+	if (!/^\d{1,15}$/.test(trimmed)) return null
+	const seconds = Number.parseInt(trimmed, 10)
+	return Number.isSafeInteger(seconds) ? seconds : null
+}
+
+/**
+ * Verify a foundryd-signed M2M request: a fresh `X-Foundry-Timestamp` (unix
+ * seconds within ±{@link SIGNATURE_MAX_SKEW_SECONDS}) plus `X-Foundry-Signature`
+ * = HMAC over `${timestamp}\n${payload}`. Returns null when authentic, or a 401
+ * Response (with a loud warn log) to short-circuit the handler.
+ */
+async function verifyFoundrySignedRequest(
+	request: Request,
+	secret: string,
+	payload: string,
+	label: string,
+): Promise<Response | null> {
+	const tsRaw = (request.headers.get('X-Foundry-Timestamp') ?? '').trim()
+	const ts = parseTimestampSeconds(tsRaw)
+	if (ts === null) {
+		console.warn(`[cms] ${label} rejected: missing or invalid X-Foundry-Timestamp`)
+		return json({ error: 'Missing or invalid X-Foundry-Timestamp' }, 401)
+	}
+	const now = Math.floor(Date.now() / 1_000)
+	if (Math.abs(now - ts) > SIGNATURE_MAX_SKEW_SECONDS) {
+		console.warn(`[cms] ${label} rejected: stale X-Foundry-Timestamp (skew ${now - ts}s)`)
+		return json({ error: 'Stale or future X-Foundry-Timestamp' }, 401)
+	}
+	const signature = request.headers.get('X-Foundry-Signature') ?? ''
+	const valid = await verifyHmac(secret, `${tsRaw}\n${payload}`, signature)
+	if (!valid) {
+		console.warn(`[cms] ${label} rejected: invalid X-Foundry-Signature`)
+		return json({ error: 'Invalid signature' }, 401)
+	}
+	return null
+}
+
+const ReceiptSchema = z.object({
+	published_urls: z.array(z.string()).nullish(),
+	platform_post_ids: z.array(z.string()).nullish(),
+	sha256: z.string().nullish(),
+})
+
+const CallbackSchema = z
+	.object({
+		event_id: z.string().min(1).optional(),
+		intent_id: z.string().min(1).nullish(),
+		content_id: z.string().min(1),
+		version: z.number().int().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(),
+		receipt: ReceiptSchema.nullish(),
+		error: z.string().nullish(),
+	})
+	.strip()
+
+export interface FrontsPublishRouteHandlers {
+	/** GET /fronts/schedule?window=<from>..<to> — items due for foundryd to publish. */
+	schedule(ctx: RouteContext): Promise<Response>
+	/** POST /fronts/publish-callback — foundryd's outbound lifecycle callback. */
+	publishCallback(ctx: RouteContext): Promise<Response>
+}
+
+/** Parse `window=<from>..<to>` into unix-seconds bounds; defaults to now..now+1h. */
+function parseWindow(
+	value: string | null,
+	nowSeconds: number,
+): { fromSeconds: number; toSeconds: number } | { error: string } {
+	if (!value) return { fromSeconds: nowSeconds, toSeconds: nowSeconds + 3600 }
+	const parts = value.split('..')
+	if (parts.length !== 2) return { error: 'window must be "<from>..<to>"' }
+	const parseBound = (raw: string): number | null => {
+		const trimmed = raw.trim()
+		if (!trimmed) return null
+		if (/^\d+$/.test(trimmed)) return Number.parseInt(trimmed, 10)
+		const ms = Date.parse(trimmed)
+		return Number.isNaN(ms) ? null : Math.floor(ms / 1_000)
+	}
+	const fromSeconds = parseBound(parts[0])
+	const toSeconds = parseBound(parts[1])
+	if (fromSeconds === null || toSeconds === null) {
+		return { error: 'window bounds must be ISO-8601 timestamps or unix seconds' }
+	}
+	if (toSeconds < fromSeconds) return { error: 'window end precedes its start' }
+	return { fromSeconds, toSeconds }
+}
+
+export function createFrontsPublishRoutes(config: CmsRouteConfig): FrontsPublishRouteHandlers {
+	const resolved = resolveConfig(config)
+	return {
+		async schedule(ctx) {
+			const hmacSecret = await resolveFoundryHmacSecret(ctx.env)
+			if (!hmacSecret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+
+			const url = new URL(ctx.request.url)
+			// The GET poll has no body; the payload is the exact query string
+			// foundryd sent (leading '?' included, or '' when empty), bound to the
+			// required timestamp so an empty-window poll can't sign a constant.
+			const denied = await verifyFoundrySignedRequest(
+				ctx.request,
+				hmacSecret,
+				url.search,
+				'fronts/schedule',
+			)
+			if (denied) return denied
+
+			if (!isFrontsPublishEnabled(ctx.env)) {
+				return json({ error: 'fronts_publish_disabled' }, 503)
+			}
+
+			const now = Math.floor(Date.now() / 1_000)
+			const window = parseWindow(url.searchParams.get('window'), now)
+			if ('error' in window) return json({ error: window.error }, 400)
+
+			// `items` is the UNCHANGED 0026 legacy schedule shape — an existing
+			// consumer keeps working byte-for-byte. `intents` is the canonical
+			// publish-intent contract (packages#500) hydrated over the SAME due
+			// 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,
+			})
+		},
+
+		async publishCallback(ctx) {
+			const hmacSecret = await resolveFoundryHmacSecret(ctx.env)
+			if (!hmacSecret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+
+			let rawBody: string
+			try {
+				rawBody = await ctx.request.text()
+			} catch {
+				return json({ error: 'Failed to read request body' }, 400)
+			}
+
+			const denied = await verifyFoundrySignedRequest(
+				ctx.request,
+				hmacSecret,
+				rawBody,
+				'fronts/publish-callback',
+			)
+			if (denied) return denied
+
+			if (!isFrontsPublishEnabled(ctx.env)) {
+				return json({ error: 'fronts_publish_disabled' }, 503)
+			}
+
+			let raw: unknown
+			try {
+				raw = JSON.parse(rawBody)
+			} catch {
+				return json({ error: 'Invalid JSON body' }, 400)
+			}
+			const parsed = CallbackSchema.safeParse(raw)
+			if (!parsed.success) {
+				return json({ error: 'Invalid payload', details: parsed.error.flatten() }, 400)
+			}
+
+			// Idempotency key: body event_id, else the Idempotency-Key header.
+			const eventId = parsed.data.event_id ?? ctx.request.headers.get('Idempotency-Key') ?? null
+			if (!eventId) {
+				return json({ error: 'Missing event_id / Idempotency-Key' }, 400)
+			}
+
+			const result = await applyFrontsPublishCallback(ctx.db, {
+				eventId,
+				intentId: parsed.data.intent_id ?? null,
+				contentId: parsed.data.content_id,
+				version: parsed.data.version ?? 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,
+			})
+
+			if (!result.contentFound) {
+				return json({ error: 'content_not_found', contentId: parsed.data.content_id }, 404)
+			}
+			if (result.ledgerError) {
+				// A confirmed `live` that could not be committed through the ledger is a
+				// hard, loud failure — never a silent zero.
+				console.error(
+					`[cms] fronts/publish-callback ledger commit failed for content ${parsed.data.content_id}: ${result.ledgerError}`,
+				)
+				return json(
+					{
+						ok: false,
+						error: 'ledger_publish_failed',
+						detail: result.ledgerError,
+						status: result.status,
+					},
+					500,
+				)
+			}
+
+			return json({
+				ok: true,
+				deduped: result.deduped,
+				status: result.status,
+				published: result.published,
+				attemptId: result.attemptId,
+			})
+		},
+	}
+}

package/src/routes/index.ts

@@ -100,6 +100,11 @@ export {
 	type DashboardRouteConfig,
 	type DashboardRouteHandlers,
 } from './dashboard.js'
+// Fronts publish surface — the HMAC schedule poll + publish-callback receiver.
+export {
+	createFrontsPublishRoutes,
+	type FrontsPublishRouteHandlers,
+} from './fronts-publish.js'
 // Import routes — two-step parse→confirm pipeline.
 export { createImportRoutes, type ImportRouteHandlers } from './imports.js'
 // Media routes.
@@ -198,6 +203,7 @@ import {
 } from './content-insights.js'
 import { type CronRouteHandlers, createCronRoutes } from './cron.js'
 import { createDashboardRoutes, type DashboardRouteHandlers } from './dashboard.js'
+import { createFrontsPublishRoutes, type FrontsPublishRouteHandlers } from './fronts-publish.js'
 import { createImportRoutes, type ImportRouteHandlers } from './imports.js'
 import { createMediaRoutes, type MediaRouteHandlers } from './media.js'
 import { createPreviewRoutes, type PreviewRouteHandlers } from './preview.js'
@@ -231,6 +237,7 @@ export interface CmsRoutes {
 	apiKeys: ApiKeyRouteHandlers
 	webhooks: WebhookRouteHandlers
 	contentInsights: ContentInsightsRouteHandlers
+	frontsPublish: FrontsPublishRouteHandlers
 }
 
 /**
@@ -297,5 +304,6 @@ export function createCmsRoutes(
 			authz: config.authz,
 			activeWorkspaceId: config.activeWorkspaceId,
 		}),
+		frontsPublish: createFrontsPublishRoutes(base),
 	}
 }