@growth-labs/cms 0.8.26 → 0.8.28

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

@@ -10,6 +10,7 @@ import {
 	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 +30,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 +183,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>
 }
@@ -231,6 +333,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

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/surveys/auto-label.ts

@@ -11,9 +11,15 @@
 // pre-filter plus <answer> delimiting so personal details never reach the
 // model and reader text is framed as data, not instructions (B2).
 
+import { z } from 'zod'
 import type { D1Database } from '../engine/d1.js'
-import type { LlmDispatch, LlmDispatchResult } from '../providers/types.js'
-import type { SurveyAnswerLabel } from './schema.js'
+import type { LlmDispatch, LlmDispatchResult, LlmDispatchSubmission } from '../providers/types.js'
+import {
+	BoundedRecordIdSchema,
+	type SurveyAnswerLabel,
+	SurveyIdSchema,
+	SurveyQuestionIdSchema,
+} from './schema.js'
 
 /** The masthead-ai-assist task for survey classification. Foundry does not
  *  validate `task` (articlechain/mastheadaiassist.go: "a sixth Masthead action
@@ -146,6 +152,9 @@ export interface SurveyAutoLabelAttemptRecord {
 	nextAt: number
 	/** Epoch ms until another request's dispatch claims this answer. */
 	inflightUntil: number
+	/** Opaque Go correlation, never reader text or identity. */
+	taskId?: string
+	reason?: 'callback_expired' | 'dispatch_failed' | 'llm_failed' | 'unparseable'
 }
 
 /** Narrow persistence the batch runner needs; the KV adapter below satisfies
@@ -154,6 +163,8 @@ export interface SurveyAutoLabelAttemptStore {
 	get(key: string): Promise<SurveyAutoLabelAttemptRecord | null>
 	put(key: string, record: SurveyAutoLabelAttemptRecord, ttlSeconds: number): Promise<void>
 	delete(key: string): Promise<void>
+	putTask?(taskId: string, record: SurveyAutoLabelTaskRecord): Promise<void>
+	getTask?(taskId: string): Promise<SurveyAutoLabelTaskRecord | null>
 }
 
 export function surveyAutoLabelAttemptKey(
@@ -175,31 +186,111 @@ interface KvLike {
 /** Attempt records in a Workers KV namespace (`survey-autolabel:` prefix).
  *  The same namespace the host's LlmDispatch result slots live in is fine:
  *  the key prefixes never collide (`masthead:llm:result:` vs ours). */
+const AttemptRecordSchema = z
+	.object({
+		attempts: z.number().int().nonnegative(),
+		nextAt: z.number().nonnegative(),
+		inflightUntil: z.number().nonnegative(),
+		taskId: z.string().min(1).max(256).optional(),
+		reason: z.enum(['callback_expired', 'dispatch_failed', 'llm_failed', 'unparseable']).optional(),
+	})
+	.strict()
+const TaskRecordSchema = z
+	.object({
+		surveyId: SurveyIdSchema,
+		responseId: BoundedRecordIdSchema,
+		questionId: SurveyQuestionIdSchema,
+		attempts: z.number().int().nonnegative(),
+	})
+	.strict()
+export type SurveyAutoLabelTaskRecord = z.infer<typeof TaskRecordSchema>
+export const SURVEY_AUTO_LABEL_TASK_PREFIX = 'survey-autolabel-task:'
+
 export function kvSurveyAutoLabelAttemptStore(kv: KvLike): SurveyAutoLabelAttemptStore {
 	return {
 		async get(key) {
 			const raw = await kv.get(key)
-			if (raw === null) return null
-			try {
-				const value = JSON.parse(raw) as Partial<SurveyAutoLabelAttemptRecord>
-				return {
-					attempts: typeof value.attempts === 'number' ? value.attempts : 0,
-					nextAt: typeof value.nextAt === 'number' ? value.nextAt : 0,
-					inflightUntil: typeof value.inflightUntil === 'number' ? value.inflightUntil : 0,
-				}
-			} catch {
-				return null
-			}
+			return raw === null ? null : AttemptRecordSchema.parse(JSON.parse(raw))
 		},
 		async put(key, record, ttlSeconds) {
-			await kv.put(key, JSON.stringify(record), { expirationTtl: ttlSeconds })
+			await kv.put(key, JSON.stringify(AttemptRecordSchema.parse(record)), {
+				expirationTtl: ttlSeconds,
+			})
 		},
 		async delete(key) {
 			await kv.delete(key)
 		},
+		async putTask(taskId, record) {
+			await kv.put(
+				`${SURVEY_AUTO_LABEL_TASK_PREFIX}${taskId}`,
+				JSON.stringify(TaskRecordSchema.parse(record)),
+				{ expirationTtl: SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS },
+			)
+		},
+		async getTask(taskId) {
+			const raw = await kv.get(`${SURVEY_AUTO_LABEL_TASK_PREFIX}${taskId}`)
+			return raw === null ? null : TaskRecordSchema.parse(JSON.parse(raw))
+		},
 	}
 }
 
+/** Finalize through the existing signed callback, independently of waitUntil.
+ * Missing correlation/persistence throws so Go retries rather than acknowledging lost work. */
+export async function finalizeSurveyAutoLabel(
+	db: D1Database,
+	store: SurveyAutoLabelAttemptStore,
+	taskId: string,
+	result: { terminalState: 'completed' | 'failed'; result?: string },
+	now = Date.now(),
+): Promise<void> {
+	const target = await store.getTask?.(taskId)
+	if (!target) throw new Error('survey correlation unavailable')
+	const key = surveyAutoLabelAttemptKey(target.surveyId, target.responseId, target.questionId)
+	const label =
+		result.terminalState === 'completed' ? parseSurveyLabelReply(result.result ?? '') : null
+	if (label) {
+		await db
+			.prepare(`INSERT INTO survey_answer_labels
+		 (survey_id, response_id, question_id, label, source, labeled_by, labeled_at)
+		 VALUES (?, ?, ?, ?, 'auto', NULL, ?)
+		 ON CONFLICT(survey_id, response_id, question_id) DO NOTHING`)
+			.bind(target.surveyId, target.responseId, target.questionId, label, now)
+			.run()
+		const current = await store.get(key)
+		if (current?.taskId === taskId) await store.delete(key)
+		return
+	}
+	const existing = await db
+		.prepare(
+			'SELECT label FROM survey_answer_labels WHERE survey_id = ? AND response_id = ? AND question_id = ? LIMIT 1',
+		)
+		.bind(target.surveyId, target.responseId, target.questionId)
+		.first()
+	if (existing) return
+	const current = await store.get(key)
+	if (!current) throw new Error('survey attempt unavailable')
+	if (
+		current.taskId === taskId &&
+		current.inflightUntil === 0 &&
+		current.attempts > target.attempts
+	)
+		return
+	// A delayed failed callback must not reset a newer retry or a completed label.
+	if (current?.taskId !== taskId) return
+	const attempts = target.attempts + 1
+	await store.put(
+		key,
+		{
+			attempts,
+			nextAt: now + SURVEY_AUTO_LABEL_BACKOFF_MS[Math.min(attempts, 3) - 1],
+			inflightUntil: 0,
+			taskId,
+			reason: result.terminalState === 'failed' ? 'llm_failed' : 'unparseable',
+		},
+		SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
+	)
+}
+
 /**
  * In-isolate in-flight gate. KV has no compare-and-swap, so a dedupe window
  * this small is enforced synchronously in module scope (all concurrent
@@ -256,18 +347,34 @@ async function runSurveyAutoLabelBatch(
 	batch: SurveyAutoLabelCandidate[],
 ): Promise<void> {
 	let cursor = 0
+	let admitted = 0
+	const reserveAdmission = () => {
+		if (admitted >= SURVEY_AUTO_LABEL_BATCH_LIMIT) return false
+		admitted += 1
+		return true
+	}
 	let stored = 0
+	let processed = 0
 	let deferred = 0
 	let halted: string | null = null
+	const admissionDeadline = (options.now ?? Date.now)() + 20_000
 	const skipReasons = new Set<string>()
 
 	const worker = async (): Promise<void> => {
 		for (;;) {
-			if (halted !== null) return
+			if (halted !== null || admitted >= SURVEY_AUTO_LABEL_BATCH_LIMIT) return
+			if ((options.now ?? Date.now)() >= admissionDeadline) {
+				halted = 'admission_window_ended'
+				return
+			}
 			const next = cursor
 			cursor += 1
 			if (next >= batch.length) return
-			const outcome = await classifyAndStore(options, batch[next])
+			const outcome = await classifyAndStore(options, batch[next], reserveAdmission).catch(() => ({
+				kind: 'unavailable' as const,
+				reason: 'attempt_write_failed',
+			}))
+			processed += 1
 			if (outcome.kind === 'stored') {
 				stored += 1
 				continue
@@ -292,7 +399,7 @@ async function runSurveyAutoLabelBatch(
 
 	// Failure-class skips only: a wholly deferred batch (all in flight or
 	// backing off) is the steady state of the dedupe, not a failure to report.
-	const skipped = batch.length - stored - deferred
+	const skipped = (halted === null ? processed : batch.length) - stored - deferred
 	if (skipped === 0) return
 	const reasons = new Set(skipReasons)
 	if (halted !== null) reasons.add(halted)
@@ -305,14 +412,19 @@ async function runSurveyAutoLabelBatch(
 
 type ClassifyOutcome =
 	| { kind: 'stored' }
-	| { kind: 'deferred'; reason: 'in_flight' | 'backoff' | 'gave_up' | 'pii' }
+	| {
+			kind: 'deferred'
+			reason: 'in_flight' | 'backoff' | 'gave_up' | 'pii' | 'empty' | 'batch_limit'
+	  }
 	| { kind: 'skipped'; reason: string }
 	| { kind: 'unavailable'; reason: string }
 
 async function classifyAndStore(
 	options: SurveyAutoLabelOptions,
 	candidate: SurveyAutoLabelCandidate,
+	reserveAdmission: () => boolean,
 ): Promise<ClassifyOutcome> {
+	if (candidate.answerText.trim().length === 0) return { kind: 'deferred', reason: 'empty' }
 	// B2 first, before any store or dispatch work: personal details never
 	// leave the Worker, and the skip consumes no attempt.
 	if (containsPersonalDetails(candidate.answerText)) return { kind: 'deferred', reason: 'pii' }
@@ -327,12 +439,25 @@ async function classifyAndStore(
 	try {
 		record = await options.attempts.get(key)
 	} catch {
-		// The attempt store is dedupe hygiene, not label correctness: an
-		// unreadable record proceeds as if absent (worst case: one duplicate
-		// dispatch, still bounded by the in-isolate gate).
+		return { kind: 'unavailable', reason: 'attempt_read_failed' }
 	}
 	if (record) {
 		if (record.inflightUntil > now) return { kind: 'deferred', reason: 'in_flight' }
+		if (record.inflightUntil > 0) {
+			const attempts = record.attempts + 1
+			await options.attempts.put(
+				key,
+				{
+					attempts,
+					nextAt: now + SURVEY_AUTO_LABEL_BACKOFF_MS[Math.min(attempts, 3) - 1],
+					inflightUntil: 0,
+					...(record.taskId ? { taskId: record.taskId } : {}),
+					reason: 'callback_expired',
+				},
+				SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
+			)
+			return { kind: 'deferred', reason: 'backoff' }
+		}
 		if (record.attempts >= SURVEY_AUTO_LABEL_MAX_ATTEMPTS) {
 			return { kind: 'deferred', reason: 'gave_up' }
 		}
@@ -340,6 +465,7 @@ async function classifyAndStore(
 	}
 	if (!reserveInFlight(key, now)) return { kind: 'deferred', reason: 'in_flight' }
 	try {
+		if (!reserveAdmission()) return { kind: 'deferred', reason: 'batch_limit' }
 		// Claimed. Record the failure (or the backoff it earns) at each exit;
 		// the KV marker goes out BEFORE the dispatch so a concurrent request
 		// in another isolate defers instead of duplicating the work.
@@ -352,23 +478,68 @@ async function classifyAndStore(
 			await options.attempts
 				.put(
 					key,
-					{ attempts, nextAt: now + backoff, inflightUntil: 0 },
+					{
+						attempts,
+						nextAt: now + backoff,
+						inflightUntil: 0,
+						reason: outcome.reason === 'unparseable' ? 'unparseable' : 'dispatch_failed',
+					},
 					SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
 				)
 				.catch(() => {})
 			return outcome
 		}
-		await options.attempts
-			.put(
-				key,
-				{
-					attempts: record?.attempts ?? 0,
-					nextAt: record?.nextAt ?? 0,
-					inflightUntil: now + SURVEY_AUTO_LABEL_INFLIGHT_MS,
-				},
-				SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
-			)
-			.catch(() => {})
+		if (!options.llm.submit)
+			await options.attempts
+				.put(
+					key,
+					{
+						attempts: record?.attempts ?? 0,
+						nextAt: record?.nextAt ?? 0,
+						inflightUntil: now + SURVEY_AUTO_LABEL_INFLIGHT_MS,
+					},
+					SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
+				)
+				.catch(() => {
+					throw new Error('attempt_write_failed')
+				})
+
+		if (options.llm.submit) {
+			if (!options.attempts.putTask)
+				return await failure({ kind: 'unavailable', reason: 'no_correlation_store' })
+			let admission: LlmDispatchSubmission
+			try {
+				admission = await options.llm.submit(
+					{
+						task: SURVEY_AUTO_LABEL_TASK,
+						prompt: buildSurveyLabelPrompt(candidate.questionPrompt, candidate.answerText),
+					},
+					async (taskId) => {
+						await options.attempts.putTask!(taskId, {
+							surveyId: options.surveyId,
+							responseId: candidate.responseId,
+							questionId: candidate.questionId,
+							attempts: record?.attempts ?? 0,
+						})
+						await options.attempts.put(
+							key,
+							{
+								attempts: record?.attempts ?? 0,
+								nextAt: 0,
+								inflightUntil: now + SURVEY_AUTO_LABEL_INFLIGHT_MS,
+								taskId,
+							},
+							SURVEY_AUTO_LABEL_ATTEMPT_TTL_SECONDS,
+						)
+					},
+				)
+			} catch {
+				return await failure({ kind: 'unavailable', reason: 'dispatch_threw' })
+			}
+			if (admission.status === 'unavailable')
+				return await failure({ kind: 'unavailable', reason: admission.reason })
+			return { kind: 'deferred', reason: 'in_flight' }
+		}
 
 		let result: LlmDispatchResult
 		try {