@growth-labs/cms 0.8.26 → 0.8.30

package/src/engine/published-content.ts

@@ -12,8 +12,8 @@ import { TagInputError, validateRevisionTaxonomy } from './taxonomy.js'
 const CONTENT_TYPES = new Set<ContentType>(['article', 'video', 'podcast', 'newsletter', 'page'])
 const CONTENT_STATUSES = new Set(['draft', 'scheduled', 'review', 'published', 'archived'])
 const CONTENT_VISIBILITIES = new Set(['free', 'premium'])
-const LIST_OPTION_KEYS = new Set(['type', 'channel', 'limit', 'cursor', 'bodies'])
-const CURSOR_KEYS = new Set(['publishedAt', 'contentId'])
+const LIST_OPTION_KEYS = new Set(['type', 'channel', 'limit', 'cursor', 'bodies', 'order'])
+const CURSOR_KEYS = new Set(['publishedAt', 'contentId', 'contentDate'])
 
 export const MAX_PUBLISHED_CONTENT_PAGE_SIZE = 100
 export const MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES = 4 * 1024 * 1024
@@ -71,6 +71,8 @@ export interface PublishedContent {
 export interface PublishedContentCursor {
 	publishedAt: number
 	contentId: string
+	/** Required when paging by the immutable snapshot's display date. */
+	contentDate?: number
 }
 
 export interface ListPublishedContentOptions {
@@ -78,6 +80,8 @@ export interface ListPublishedContentOptions {
 	channel?: string
 	limit?: number
 	cursor?: PublishedContentCursor | null
+	/** Preserve canonical order by default; card lists may order by snapshot date. */
+	order?: 'published' | 'content-date'
 	/**
 	 * `false` strips `content.body_markdown` / `content.body_html` from each
 	 * payload IN SQL, so corpus snapshots (lists, navs, hubs) stop hauling the
@@ -110,6 +114,7 @@ interface PublishedContentOutlineRow {
 	pointer_revision_id: string
 	canonical_published_at: number
 	payload_bytes: number
+	content_date?: number
 }
 
 const SELECT_PUBLISHED_CONTENT = `
@@ -149,23 +154,22 @@ SELECT
 FROM content_items ci
 `
 
-const SELECT_PUBLISHED_CONTENT_OUTLINE = `
+function publishedOutlineSelect(bodies: boolean, contentDate: string): string {
+	return `
 SELECT
   ci.id AS content_id,
   ci.published_revision_id AS pointer_revision_id,
   ci.published_at AS canonical_published_at,
-  length(CAST(cr.payload_json AS BLOB)) AS payload_bytes
+  ${contentDate} AS content_date,
+  length(CAST(${bodies ? 'cr.payload_json' : BODYLESS_PAYLOAD_EXPR} AS BLOB)) AS payload_bytes
 FROM content_items ci
 `
+}
 
-const SELECT_PUBLISHED_CONTENT_OUTLINE_BODYLESS = `
-SELECT
-  ci.id AS content_id,
-  ci.published_revision_id AS pointer_revision_id,
-  ci.published_at AS canonical_published_at,
-  length(CAST(${BODYLESS_PAYLOAD_EXPR} AS BLOB)) AS payload_bytes
-FROM content_items ci
-`
+const SNAPSHOT_CONTENT_DATE = `CASE WHEN json_valid(cr.payload_json) = 1
+THEN COALESCE(json_extract(cr.payload_json, '$.item.publish_at'),
+  json_extract(cr.payload_json, '$.item.published_at'), 0)
+ELSE 0 END`
 
 const SELECT_PUBLISHED_CONTENT_BY_SLUG = `
 SELECT
@@ -465,6 +469,7 @@ function normalizeListOptions(options: unknown): {
 	type?: ContentType
 	channel?: string
 	cursor?: PublishedContentCursor
+	order: 'published' | 'content-date'
 } {
 	if (!isPlainRecord(options)) {
 		throw new PublishedContentReadError(
@@ -506,6 +511,13 @@ function normalizeListOptions(options: unknown): {
 		channel = options.channel
 	}
 	let cursor: PublishedContentCursor | undefined
+	const order = options.order ?? 'published'
+	if (order !== 'published' && order !== 'content-date') {
+		throw new PublishedContentReadError(
+			'published_content_input_invalid',
+			'unknown published content order',
+		)
+	}
 	if (options.cursor !== undefined && options.cursor !== null) {
 		if (
 			!isPlainRecord(options.cursor) ||
@@ -527,9 +539,22 @@ function normalizeListOptions(options: unknown): {
 			)
 		}
 		assertLookupValue(options.cursor.contentId, 'cursor contentId', 256)
+		if (
+			(order === 'content-date' &&
+				(typeof options.cursor.contentDate !== 'number' ||
+					!Number.isSafeInteger(options.cursor.contentDate) ||
+					options.cursor.contentDate < 0)) ||
+			(order === 'published' && options.cursor.contentDate !== undefined)
+		) {
+			throw new PublishedContentReadError(
+				'published_content_input_invalid',
+				'cursor must match the requested content order',
+			)
+		}
 		cursor = {
 			publishedAt: options.cursor.publishedAt,
 			contentId: options.cursor.contentId,
+			...(order === 'content-date' ? { contentDate: options.cursor.contentDate as number } : {}),
 		}
 	}
 	let bodies = true
@@ -548,6 +573,7 @@ function normalizeListOptions(options: unknown): {
 		type,
 		channel,
 		cursor,
+		order,
 	}
 }
 
@@ -563,6 +589,12 @@ export async function listPublishedContent(
 		'ci.published_at IS NOT NULL',
 	]
 	const values: unknown[] = []
+	const contentDate =
+		normalized.order === 'content-date' ? SNAPSHOT_CONTENT_DATE : 'ci.published_at'
+	const orderBy =
+		normalized.order === 'content-date'
+			? `${contentDate} DESC, ci.published_at DESC, ci.id DESC`
+			: 'ci.published_at DESC, ci.id DESC'
 	// A missing revision or type must reach the integrity checks, rather than
 	// disappearing behind a type/channel filter as a successful empty list.
 	const invalidRevisionType = `CASE WHEN json_valid(cr.payload_json) = 1
@@ -580,7 +612,15 @@ ELSE 1 END`
 		values.push(normalized.channel)
 	}
 	if (normalized.cursor) {
-		predicates.push('(ci.published_at < ? OR (ci.published_at = ? AND ci.id < ?))')
+		const canonicalCursor = '(ci.published_at < ? OR (ci.published_at = ? AND ci.id < ?))'
+		predicates.push(
+			normalized.order === 'content-date'
+				? `(${contentDate} < ? OR (${contentDate} = ? AND ${canonicalCursor}))`
+				: canonicalCursor,
+		)
+		if (normalized.order === 'content-date') {
+			values.push(normalized.cursor.contentDate, normalized.cursor.contentDate)
+		}
 		values.push(
 			normalized.cursor.publishedAt,
 			normalized.cursor.publishedAt,
@@ -591,10 +631,10 @@ ELSE 1 END`
 		const reader = openReadSession(db)
 		const outlineResult = await reader
 			.prepare(
-				`${normalized.bodies ? SELECT_PUBLISHED_CONTENT_OUTLINE : SELECT_PUBLISHED_CONTENT_OUTLINE_BODYLESS}
+				`${publishedOutlineSelect(normalized.bodies, contentDate)}
 LEFT JOIN content_revisions cr ON cr.id = ci.published_revision_id
 WHERE ${predicates.join('\n  AND ')}
-ORDER BY ci.published_at DESC, ci.id DESC
+ORDER BY ${orderBy}
 LIMIT ?`,
 			)
 			.bind(...values, normalized.limit + 1)
@@ -616,6 +656,17 @@ LIMIT ?`,
 					'published revision outline is malformed',
 				)
 			}
+			if (
+				normalized.order === 'content-date' &&
+				(typeof outline.content_date !== 'number' ||
+					!Number.isSafeInteger(outline.content_date) ||
+					outline.content_date < 0)
+			) {
+				throw new PublishedContentReadError(
+					'published_payload_invalid',
+					'published snapshot date is malformed',
+				)
+			}
 			if (outline.payload_bytes > MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES) {
 				throw new PublishedContentReadError(
 					'published_payload_limit_exceeded',
@@ -689,7 +740,15 @@ WHERE ci.status = 'published'
 		return {
 			items,
 			nextCursor:
-				hasMore && last ? { publishedAt: last.publishedAt, contentId: last.contentId } : null,
+				hasMore && last
+					? {
+							publishedAt: last.publishedAt,
+							contentId: last.contentId,
+							...(normalized.order === 'content-date'
+								? { contentDate: selected.at(-1)?.content_date }
+								: {}),
+						}
+					: null,
 		}
 	} catch (error) {
 		return wrapReadError(error)

package/src/index.ts

@@ -85,5 +85,6 @@ export {
 	type WorkspaceMembershipRow,
 	type WorkspaceSettingsRow,
 } from './schema/index.js'
+export { finalizeSurveyAutoLabel, kvSurveyAutoLabelAttemptStore } from './surveys/auto-label.js'
 export * from './surveys/errors.js'
 export * from './surveys/schema.js'

package/src/integration/options.ts

@@ -1,6 +1,6 @@
 import { isCanonicalHost } from '@growth-labs/foundry-signing'
 import { z } from 'zod'
-import { SurveyIdSchema } from '../surveys/schema.js'
+import { SurveyFeedbackThemesSchema, SurveyIdSchema } from '../surveys/schema.js'
 
 const workspaceSchema = z.object({
 	id: z.string(),
@@ -121,9 +121,29 @@ const socialSharingSchema = z
 
 const surveyResultsSchema = z
 	.object({
+		// The survey the screen opens on.
 		surveyId: SurveyIdSchema,
+		// Every survey the screen can switch between, in picker order. Absent
+		// means only surveyId; when given it must include surveyId.
+		surveys: z
+			.array(
+				z
+					.object({
+						surveyId: SurveyIdSchema,
+						label: z.string().trim().min(1).max(80),
+						feedbackThemes: SurveyFeedbackThemesSchema.optional(),
+					})
+					.strict(),
+			)
+			.min(1)
+			.max(10)
+			.optional(),
 	})
 	.strict()
+	.refine(
+		(value) => !value.surveys || value.surveys.some((survey) => survey.surveyId === value.surveyId),
+		{ message: 'surveyResults.surveys must include surveyResults.surveyId' },
+	)
 
 const surveysOptionsSchema = z
 	.object({

package/src/providers/types.ts

@@ -440,8 +440,17 @@ export type LlmDispatchResult =
 	| { text: string; status?: 'ok' }
 	| { text: string; status: 'unavailable'; reason?: string }
 	| ReadableStream
+export type LlmDispatchSubmission =
+	| { status: 'accepted'; taskId: string }
+	| { status: 'unavailable'; reason: string }
 export interface LlmDispatch {
 	dispatch(input: LlmDispatchInput): Promise<LlmDispatchResult>
+	/** Admit background work without waiting for the signed terminal callback.
+	 * Persist correlation before the outbound request; failure must prevent dispatch. */
+	submit?(
+		input: LlmDispatchInput,
+		beforeDispatch: (taskId: string) => Promise<void>,
+	): Promise<LlmDispatchSubmission>
 }
 
 export interface FoundryJobSpec {

package/src/routes/content-insights.ts

@@ -6,10 +6,12 @@ import {
 	isMissingInsightPublicationSchema,
 	isMissingInsightsTable,
 	listInsightBoard,
+	readSelectedClusterMembership,
 	replaceInsightsBoard,
 	undismissInsight,
 } from '../engine/content-insights.js'
 import { verifyHmac } from '../engine/foundry-dispatch.js'
+import { 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'
@@ -29,6 +31,103 @@ const DismissSchema = z
 	.strict()
 const IntentKeySchema = z.object({ intentKey: z.string().min(1) })
 
+const PublishedCursorSchema = z
+	.object({
+		publishedAt: z.number().int().nonnegative(),
+		contentId: z.string().min(1).max(256),
+	})
+	.strict()
+
+const PublishedArticleStateSchema = z
+	.object({
+		content_id: z.string().min(1),
+		revision_id: z.string().min(1),
+		slug: z.string().min(1),
+		title: z.string().min(1),
+		canonical_url: z.string().url().nullable(),
+		published_at: z.number().int().nonnegative(),
+		source_id: z.string().nullable(),
+		youtube_video_id: z
+			.string()
+			.regex(/^[A-Za-z0-9_-]{11}$/)
+			.nullable(),
+		hero_image_id: z.string().nullable(),
+		hero_image_caption: z.string().nullable(),
+	})
+	.strict()
+
+const PublishedInputsResponseSchema = z
+	.object({
+		ok: z.literal(true),
+		site: z.string().min(1),
+		observed_at: z.string().datetime(),
+		published: z.array(PublishedArticleStateSchema),
+		next_cursor: PublishedCursorSchema.nullable(),
+		complete: z.boolean(),
+	})
+	.strict()
+
+// Additive read mode of the existing signed inputs route. Read the immutable
+// published snapshot, never mutable draft fields. Reuse the CMS reader's
+// revision checks and pagination; return only named public fields, not a raw
+// payload that may contain internal machine trigger tokens.
+async function publishedInputs(ctx: RouteContext, url: URL, siteId: string): Promise<Response> {
+	if (url.searchParams.get('published') !== '1')
+		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 limit = z.coerce
+		.number()
+		.int()
+		.min(1)
+		.max(100)
+		.safeParse(url.searchParams.get('limit') ?? '100')
+	if (!limit.success) return json({ error: 'invalid_limit' }, 400)
+	let cursor: z.infer<typeof PublishedCursorSchema> | null = null
+	const cursorText = url.searchParams.get('cursor')
+	if (cursorText !== null) {
+		try {
+			const parsed = PublishedCursorSchema.safeParse(JSON.parse(cursorText))
+			if (!parsed.success) return json({ error: 'invalid_cursor' }, 400)
+			cursor = parsed.data
+		} catch {
+			return json({ error: 'invalid_cursor' }, 400)
+		}
+	}
+	try {
+		const page = await listPublishedContent(ctx.db, {
+			type: 'article',
+			bodies: false,
+			limit: limit.data,
+			cursor,
+		})
+		const result = PublishedInputsResponseSchema.safeParse({
+			ok: true,
+			site: siteId,
+			observed_at: new Date().toISOString(),
+			published: page.items.map((content) => ({
+				content_id: content.contentId,
+				revision_id: content.revisionId,
+				slug: content.slug,
+				title: content.payload.item.title,
+				canonical_url: content.payload.item.canonical_url ?? null,
+				published_at: content.publishedAt,
+				source_id: content.payload.item.source_id ?? null,
+				youtube_video_id: content.metadata.videoId ?? null,
+				hero_image_id: content.payload.item.hero_image_id ?? null,
+				hero_image_caption: content.payload.item.hero_image_caption ?? null,
+			})),
+			next_cursor: page.nextCursor,
+			complete: page.nextCursor === null,
+		})
+		if (!result.success) return json({ error: 'published_state_invalid' }, 409)
+		return json(result.data)
+	} catch (error) {
+		if (error instanceof PublishedContentReadError) return json({ error: error.code }, 409)
+		throw error
+	}
+}
+
 /** Resolve YYYY-MM-DD; defaults to the current UTC date when no ?runDate is given. */
 function resolveRunDate(ctx: RouteContext): string {
 	const url = new URL(ctx.request.url)
@@ -85,6 +184,10 @@ export interface ContentInsightsRouteHandlers {
 	 * fronts/schedule (X-Foundry-Timestamp + X-Foundry-Signature over the raw
 	 * query string, verified against FOUNDRY_HMAC_SECRET) -- a sibling poll,
 	 * not a new auth scheme.
+	 * `published=1&site=<configured-publication>` reads a page of canonical
+	 * published article revisions instead, with `limit` (1..100) and JSON
+	 * `cursor` from the prior page. `complete` means the pagination ended;
+	 * no total is inferred from one page. Missing URLs/video IDs are null.
 	 */
 	insightsInputs(ctx: RouteContext): Promise<Response>
 }
@@ -210,7 +313,11 @@ export function createContentInsightsRoutes(
 			} catch (error) {
 				if (isMissingInsightPublicationSchema(error))
 					return json({ error: 'schema_not_ready' }, 409)
-				if (error instanceof InsightPublicationError) return json({ error: error.code }, 409)
+				if (error instanceof InsightPublicationError)
+					return json(
+						{ error: error.code },
+						error.code === 'selected_membership_replacement_refused' ? 422 : 409,
+					)
 				throw error
 			}
 		},
@@ -219,7 +326,13 @@ export function createContentInsightsRoutes(
 		// family as fronts/schedule (timestamp-bound signature over the query
 		// string; a GET has no body to bind freshness to instead).
 		async insightsInputs(ctx) {
-			const hmacSecret = await resolveFoundryHmacSecretForInputs(ctx.env)
+			// Channel publications use the existing shared CMS binding. An explicit
+			// legacy binding retains precedence, including loud failure if unreadable.
+			const binding =
+				ctx.env?.FOUNDRY_HMAC_SECRET === undefined
+					? 'CMS_FOUNDRY_HMAC_SECRET'
+					: 'FOUNDRY_HMAC_SECRET'
+			const hmacSecret = await resolveFoundryHmacSecretForInputs(ctx.env, binding)
 			if (!hmacSecret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
 
 			const url = new URL(ctx.request.url)
@@ -231,6 +344,8 @@ export function createContentInsightsRoutes(
 			)
 			if (denied) return denied
 
+			if (url.searchParams.has('published')) return publishedInputs(ctx, url, siteId)
+
 			const requestedSite = url.searchParams.get('site')
 			const authorsResult = await ctx.db.prepare(AUTHORS_QUERY).all<{
 				name: string
@@ -240,11 +355,38 @@ export function createContentInsightsRoutes(
 				title: string
 				slug: string
 			}>()
+			let selected: Awaited<ReturnType<typeof readSelectedClusterMembership>> | null = null
+			// Membership cannot ride the historical requested-site echo: it is
+			// returned only for this configured publication's signed request.
+			if (siteId !== 'default' && requestedSite === siteId) {
+				try {
+					selected = await readSelectedClusterMembership(ctx.db, siteId)
+				} catch (error) {
+					if (
+						!(error instanceof Error && error.message.startsWith('cluster_membership_unknown:')) &&
+						!isMissingInsightsTable(error)
+					)
+						throw error
+				}
+			}
 			return json({
 				ok: true,
 				site: requestedSite ?? siteId,
 				authors: authorsResult.results ?? [],
 				existing: existingResult.results ?? [],
+				cluster_membership: selected ? 'selected' : 'unknown',
+				cluster_selections:
+					selected?.map((membership) => ({
+						site_id: membership.site_id,
+						intent_key: membership.intent_key,
+						desk: membership.desk,
+						decision_ref: membership.decision_ref,
+						taxonomy_ref: membership.taxonomy_ref,
+						hub_content_id: membership.hub.content_id,
+						hub_revision_id: membership.hub.revision_id,
+						child_content_ids: membership.children.map((page) => page.content_id),
+						child_revision_ids: membership.children.map((page) => page.revision_id),
+					})) ?? null,
 			})
 		},
 	}

package/src/routes/fronts-publish.ts

@@ -60,8 +60,9 @@ 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',
 ): Promise<string | null> {
-	const raw = env?.FOUNDRY_HMAC_SECRET
+	const raw = env?.[binding]
 	if (typeof raw === 'string') return raw || null
 	if (raw && typeof (raw as { get?: unknown }).get === 'function') {
 		try {

package/src/routes/surveys.ts

@@ -5,10 +5,11 @@ import { type CmsProviders, type LlmDispatch, ProviderHttpError } from '../provi
 import { canLabelSurveyAnswers } from '../surveys/access.js'
 import {
 	containsPersonalDetails,
-	SURVEY_AUTO_LABEL_BATCH_LIMIT,
+	SURVEY_AUTO_LABEL_MAX_ATTEMPTS,
 	type SurveyAutoLabelAttemptStore,
 	type SurveyAutoLabelCandidate,
 	scheduleSurveyAutoLabel,
+	surveyAutoLabelAttemptKey,
 } from '../surveys/auto-label.js'
 import {
 	SURVEY_ERROR_CODE_HEADER,
@@ -86,7 +87,15 @@ export function createSurveyRoutes(config: SurveyRouteConfig): SurveyRouteHandle
 				scheduleAutoLabelIfEnabled(ctx, config, surveyId, unlabeled)
 				return responseJson(
 					canLabelSurveyAnswers(caller?.role)
-						? withOwnerLabelCounts(withOwnerLabels(parsed.data, labels), unlabeled)
+						? await withOwnerClassificationStatus(
+								withOwnerLabelCounts(
+									withOwnerLabels(parsed.data, labels, !!config.autoLabel),
+									unlabeled,
+								),
+								config,
+								surveyId,
+								unlabeled,
+							)
 						: withholdNonGeneralAnswers(parsed.data, labels),
 				)
 			} catch (error) {
@@ -334,9 +343,43 @@ function nonOwnerAnswer(
  * automatic ones). Non-owner payloads are never decorated — they pass through
  * withholdNonGeneralAnswers untouched.
  */
-function withOwnerLabels(data: SurveyResults, labels: AnswerLabelIndex): SurveyResults {
+function withOwnerLabels(
+	data: SurveyResults,
+	labels: AnswerLabelIndex,
+	exposeWrittenChoices = false,
+): SurveyResults {
+	const questions = questionIndex(data)
+	const writtenChoices = new Map(
+		unlabeledWrittenAnswers(data, new Map())
+			.filter((candidate) => !questions.textQuestionIds.has(candidate.questionId))
+			.map((candidate) => [
+				answerLabelKey(candidate.responseId, candidate.questionId),
+				candidate.answerText,
+			]),
+	)
 	return {
 		...data,
+		responses: exposeWrittenChoices
+			? data.responses.map((response) => ({
+					...response,
+					answers: response.answers?.map((answer) => {
+						const key = answerLabelKey(response.id, answer.questionId)
+						const writtenValue = writtenChoices.get(key)
+						if (writtenValue === undefined) return answer
+						const row = labels.get(key)
+						return {
+							...answer,
+							writtenValue,
+							...(row
+								? {
+										label: row.label,
+										...(isAnswerLabelSource(row.source) ? { labelSource: row.source } : {}),
+									}
+								: {}),
+						}
+					}),
+				}))
+			: data.responses,
 		freeText: data.freeText.map((entry) => {
 			const row = labels.get(answerLabelKey(entry.responseId, entry.questionId))
 			if (row === undefined) return entry
@@ -372,6 +415,64 @@ function withOwnerLabelCounts(
 	}
 }
 
+/** Classification status contains fixed states and timestamps, never model replies/errors. */
+async function withOwnerClassificationStatus(
+	data: SurveyResults,
+	config: SurveyRouteConfig,
+	surveyId: string,
+	unlabeled: SurveyAutoLabelCandidate[],
+): Promise<SurveyResults> {
+	if (!config.autoLabel) return data
+	type Status = Pick<SurveyResults['freeText'][number], 'classificationStatus' | 'nextAttemptAt'>
+	const states = new Map<string, Status>(
+		await Promise.all(
+			unlabeled.map(async (candidate): Promise<[string, Status]> => {
+				const key = answerLabelKey(candidate.responseId, candidate.questionId)
+				if (containsPersonalDetails(candidate.answerText))
+					return [key, { classificationStatus: 'manual_review' }]
+				try {
+					const record = await config.autoLabel!.attempts.get(
+						surveyAutoLabelAttemptKey(surveyId, candidate.responseId, candidate.questionId),
+					)
+					const now = Date.now()
+					const classificationStatus: Status['classificationStatus'] = !record
+						? 'queued'
+						: record.inflightUntil > now
+							? 'pending'
+							: record.inflightUntil > 0
+								? 'expired'
+								: record.attempts >= SURVEY_AUTO_LABEL_MAX_ATTEMPTS
+									? 'manual_review'
+									: record.reason
+										? 'retry'
+										: 'queued'
+					return [
+						key,
+						{ classificationStatus, ...(record?.nextAt ? { nextAttemptAt: record.nextAt } : {}) },
+					]
+				} catch {
+					return [key, { classificationStatus: 'unavailable' }]
+				}
+			}),
+		),
+	)
+	return {
+		...data,
+		freeText: data.freeText.map((entry) => ({
+			...entry,
+			...states.get(answerLabelKey(entry.responseId, entry.questionId)),
+		})),
+		responses: data.responses.map((response) => ({
+			...response,
+			answers: response.answers?.map((answer) =>
+				answer.writtenValue === undefined
+					? answer
+					: { ...answer, ...states.get(answerLabelKey(response.id, answer.questionId)) },
+			),
+		})),
+	}
+}
+
 /**
  * Hand the current page's unlabeled written answers to the background
  * labeler (surveys.autoLabel). A no-op unless the option is on, the host
@@ -386,7 +487,7 @@ function scheduleAutoLabelIfEnabled(
 	unlabeled: SurveyAutoLabelCandidate[],
 ): void {
 	if (!config.autoLabel?.llm || !ctx.waitUntil) return
-	const batch = unlabeled.slice(0, SURVEY_AUTO_LABEL_BATCH_LIMIT)
+	const batch = unlabeled
 	if (batch.length === 0) return
 	scheduleSurveyAutoLabel(
 		{
@@ -418,6 +519,7 @@ function unlabeledWrittenAnswers(
 	const candidates: SurveyAutoLabelCandidate[] = []
 	const seen = new Set<string>()
 	const consider = (responseId: string, questionId: string, answerText: string) => {
+		if (answerText.trim().length === 0) return
 		const key = answerLabelKey(responseId, questionId)
 		if (seen.has(key) || labels.has(key)) return
 		seen.add(key)

package/src/schema/insights-ingest.ts

@@ -115,12 +115,42 @@ export const InsightCompetitorArticleSchema = z.object({
 	covered: z.boolean().optional(),
 })
 
+const PublishedClusterPageSchema = z
+	.object({
+		content_id: z.string().min(1),
+		revision_id: z.string().min(1),
+		url: z.string().url(),
+		title: z.string().min(1),
+	})
+	.strict()
+
+export const InsightSelectedClusterMembershipSchema = z
+	.object({
+		site_id: z.string().min(1),
+		run_id: z.string().min(1),
+		intent_key: z.string().min(1),
+		desk: z.string().min(1),
+		decision_ref: z.string().min(1),
+		taxonomy_ref: z.string().min(1),
+		hub: PublishedClusterPageSchema,
+		children: z.array(PublishedClusterPageSchema).min(4),
+	})
+	.strict()
+	.refine((membership) => {
+		const members = [membership.hub, ...membership.children]
+		return (
+			new Set(members.map((page) => page.content_id)).size === members.length &&
+			new Set(members.map((page) => page.url)).size === members.length
+		)
+	}, 'selected hub and children must be distinct published pages')
+
 export const InsightBriefSchema = z.object({
 	why_now: z.string().min(1),
 	angle: z.string().min(1),
 	cluster: z.object({
 		canonical: z.string().min(1),
 		spokes: z.array(z.string().min(1)),
+		selected: InsightSelectedClusterMembershipSchema.optional(),
 	}),
 	sources: z.array(
 		z.object({
@@ -200,6 +230,21 @@ export const InsightsIngestPayloadSchema = z
 	// replace DELETE by meta.site_id + meta.run_date — never run_date alone).
 	.superRefine((payload, ctx) => {
 		for (const [i, row] of payload.rows.entries()) {
+			const selected = row.brief.cluster.selected
+			if (
+				selected &&
+				(selected.site_id !== row.site_id ||
+					selected.run_id !== payload.meta.run_id ||
+					selected.intent_key !== row.intent_key ||
+					selected.desk !== row.desk)
+			) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['rows', i, 'brief', 'cluster', 'selected'],
+					message:
+						'selected membership must bind the same site, run, desk and intent as its signed row',
+				})
+			}
 			if (row.site_id !== payload.meta.site_id || row.run_date !== payload.meta.run_date) {
 				ctx.addIssue({
 					code: z.ZodIssueCode.custom,