@case-framework/survey-assistant 0.2.2 → 0.2.3

package/dist/{engine-0AJrv0hI.mjs → engine-CWTuN3o2.mjs}

@@ -1,5 +1,5 @@
-import { P as rawSurveyDocumentSchema, c as surveyAssistantTurnFinalSchema, u as surveyChangeSetSchema } from "./protocol-DpCYmCjr.mjs";
-import { n as assertSurveyAssistantCapabilities } from "./capabilities-DKbNCnBf.mjs";
+import { I as rawSurveyDocumentSchema, f as surveyChangeSetSchema, l as surveyAssistantTurnFinalSchema } from "./protocol-DATvkr1S.mjs";
+import { a as normalizeFormAuthoringConfig, c as assertSurveyAssistantCapabilities, i as isValidSimpleFormConfig, o as transitionFormAuthoringMode, r as isCompatibleSimpleFieldUpsert, t as getFormAuthoringMode } from "./form-authoring-DCd9XfXf.mjs";
 import { z } from "zod";
 import { ContentType, Expression, ExpressionType, FunctionExpressionNames, JsonPatchError, ReservedSurveyItemTypes, SurveyItemTranslations, SurveyTranslations, ValueReferenceMethod, ValueType, applyJsonPatch, generateId, getContentPlainText, isContentEmpty, parseJsonPointer, structuredCloneMethod } from "@case-framework/survey-core";
 //#region src/engine/context.ts
@@ -483,6 +483,8 @@ const choiceOptionDetailsSchema = z.object({
 	hasDisplayCondition: z.boolean().optional(),
 	embeddedFormItemId: z.string().optional(),
 	embeddedFormFieldGroupCount: z.number().int().nonnegative().optional(),
+	embeddedFormAuthoringMode: z.enum(["simple", "custom"]).optional(),
+	embeddedFormSimpleModeValid: z.boolean().optional(),
 	embeddedFormTranslationPrefix: z.string().optional(),
 	embeddedFormResponseSlotPrefix: z.string().optional()
 });
@@ -535,6 +537,8 @@ const itemConfigDetailsSchema = z.object({
 		"generic"
 	]),
 	summary: z.array(z.string()),
+	authoringMode: z.enum(["simple", "custom"]).optional(),
+	simpleModeValid: z.boolean().optional(),
 	mainResponseSlotId: z.string().optional(),
 	choiceOptions: z.array(choiceOptionDetailsSchema).optional(),
 	formFieldGroups: z.array(formFieldGroupDetailsSchema).optional(),
@@ -677,7 +681,8 @@ const buildChoiceConfigDetails = (rawItem) => {
 		if (!isRecord$5(option)) return;
 		const id = asString(option.id);
 		if (!id) return;
-		const embeddedFormFieldGroups = asArray((isRecord$5(option.embeddedForm) ? option.embeddedForm : void 0)?.fieldGroups);
+		const embeddedForm = isRecord$5(option.embeddedForm) ? option.embeddedForm : void 0;
+		const embeddedFormFieldGroups = asArray(embeddedForm?.fieldGroups);
 		const details = {
 			position: index + 1,
 			id,
@@ -691,6 +696,8 @@ const buildChoiceConfigDetails = (rawItem) => {
 		if (embeddedFormItemId) details.embeddedFormItemId = embeddedFormItemId;
 		if (embeddedFormFieldGroups.length > 0) {
 			details.embeddedFormFieldGroupCount = embeddedFormFieldGroups.length;
+			details.embeddedFormAuthoringMode = getFormAuthoringMode(embeddedForm);
+			details.embeddedFormSimpleModeValid = isValidSimpleFormConfig(embeddedForm);
 			details.embeddedFormTranslationPrefix = getChoiceEmbeddedFormTranslationPrefix(id);
 			details.embeddedFormResponseSlotPrefix = getChoiceEmbeddedFormResponseSlotPrefix(id);
 		}
@@ -754,7 +761,8 @@ const buildFormFieldDetails = (field, position, translationNamespace, responseSl
 };
 const buildFormConfigDetails = (rawItem, configOverride, translationNamespace, responseSlotPrefix) => {
 	const configCandidate = configOverride ?? rawItem.config;
-	const rawGroups = asArray((isRecord$5(configCandidate) ? configCandidate : void 0)?.fieldGroups);
+	const config = isRecord$5(configCandidate) ? configCandidate : void 0;
+	const rawGroups = asArray(config?.fieldGroups);
 	if (rawItem.itemType !== "formItem" && rawGroups.length === 0) return;
 	const formFieldGroups = rawGroups.map((group, groupIndex) => {
 		if (!isRecord$5(group)) return;
@@ -780,9 +788,13 @@ const buildFormConfigDetails = (rawItem, configOverride, translationNamespace, r
 		};
 	}).filter((group) => Boolean(group));
 	const fieldCount = formFieldGroups.reduce((sum, group) => sum + group.fieldCount, 0);
+	const authoringMode = getFormAuthoringMode(config);
+	const simpleModeValid = isValidSimpleFormConfig(config);
 	return {
 		kind: "form",
-		summary: [`form item config: ${formFieldGroups.length} group(s), ${fieldCount} field(s)`],
+		summary: [`form item config: authoringMode=${authoringMode}, ${formFieldGroups.length} group(s), ${fieldCount} field(s)${simpleModeValid ? "" : "; malformed simple mode should be treated as custom"}`],
+		authoringMode,
+		simpleModeValid,
 		formFieldGroups,
 		listOrdering: {
 			formFieldGroups: "Stored configured order; positions are one-based.",
@@ -1942,6 +1954,12 @@ const MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT = 1e3;
 const CHOICE_ITEM_TYPE = "choiceItem";
 const FORM_ITEM_TYPE = "formItem";
 const CHOICE_OPTION_LABEL_CONTENT_KEY_PATTERN = /^options\.([^.]+)\.label$/;
+const MAX_VALIDATION_DIAGNOSTIC_VALUES = 12;
+const formatBoundedDiagnosticValues = (values, limit = MAX_VALIDATION_DIAGNOSTIC_VALUES) => {
+	const shown = values.slice(0, limit);
+	const suffix = shown.length < values.length ? `, … (${shown.length}/${values.length} shown in operation order)` : "";
+	return `${shown.join(", ")}${suffix}`;
+};
 const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const getTrimmedString = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 const getFirstStringProperty = (record, keys) => {
@@ -2182,7 +2200,7 @@ const validateNewRawPatchLocalizedContent = ({ operation, originalSurvey, patche
 	if (missing.length === 0) return [];
 	return [createIssue({
 		code: "missing-raw-patch-localized-content",
-		message: `The raw patch introduces respondent-visible content without its required translation. Add non-empty Content values in the same patches array for: ${missing.map(({ itemId, contentKey }) => `/translations/<locale>/itemTranslations/${itemId}/${contentKey}`).join(", ")}. Content keys use config ids exactly and are case-sensitive; for embedded fields, embeddedForms.<optionId> uses the choice option's id, not its key or embeddedForm id.`,
+		message: `The raw patch introduces respondent-visible content without its required translation. Add non-empty Content values in the same patches array for: ${formatBoundedDiagnosticValues(missing.map(({ itemId, contentKey }) => `/translations/<locale>/itemTranslations/${itemId}/${contentKey}`))}. Content keys use config ids exactly and are case-sensitive; for embedded fields, embeddedForms.<optionId> uses the choice option's id, not its key or embeddedForm id.`,
 		operationIndex: 0,
 		operationId: getOperationId(operation),
 		itemId: missing[0]?.itemId
@@ -2587,6 +2605,7 @@ const isSurveyLevelOperation = (operation) => [
 	"update-survey-metadata",
 	"update-survey-pagination",
 	"update-survey-translation",
+	"add-survey-locale",
 	"remove-survey-locale",
 	"set-image-asset",
 	"update-image-asset-metadata",
@@ -2605,6 +2624,7 @@ const getOperationTarget = (operation) => {
 		case "update-survey-metadata":
 		case "update-survey-pagination":
 		case "update-survey-translation":
+		case "add-survey-locale":
 		case "remove-survey-locale":
 		case "set-image-asset":
 		case "update-image-asset-metadata":
@@ -2714,17 +2734,26 @@ const getFormFieldGroupsForTarget = (rawItem, optionId) => {
 	const option = getChoiceOptionsFromRawItem(rawItem).find((candidate) => candidate.id === optionId);
 	return option ? getFormFieldGroupsFromConfig(option.embeddedForm) : void 0;
 };
-const withFormFieldGroupsForTarget = (rawItem, fieldGroups, optionId) => {
+const getFormConfigForTarget = (rawItem, optionId) => {
+	if (!optionId) return rawItem.itemType === FORM_ITEM_TYPE && isRecord$2(rawItem.config) ? rawItem.config : void 0;
+	if (rawItem.itemType !== CHOICE_ITEM_TYPE) return void 0;
+	const option = getChoiceOptionsFromRawItem(rawItem).find((candidate) => candidate.id === optionId);
+	return option && isRecord$2(option.embeddedForm) ? option.embeddedForm : void 0;
+};
+const withFormFieldGroupsForTarget = (rawItem, fieldGroups, optionId, preserveSimpleMode = false) => {
 	if (!optionId) {
 		if (rawItem.itemType !== FORM_ITEM_TYPE) return void 0;
 		const config = isRecord$2(rawItem.config) ? rawItem.config : {};
 		return {
 			...rawItem,
-			config: {
-				id: rawItem.id,
-				...config,
-				fieldGroups
-			}
+			config: transitionFormAuthoringMode({
+				config: {
+					id: rawItem.id,
+					...config
+				},
+				fieldGroups,
+				preserveSimpleMode
+			})
 		};
 	}
 	if (rawItem.itemType !== CHOICE_ITEM_TYPE) return void 0;
@@ -2735,11 +2764,14 @@ const withFormFieldGroupsForTarget = (rawItem, fieldGroups, optionId) => {
 	const embeddedForm = isRecord$2(option.embeddedForm) ? option.embeddedForm : {};
 	options[optionIndex] = {
 		...option,
-		embeddedForm: {
-			id: optionId,
-			...embeddedForm,
-			fieldGroups
-		}
+		embeddedForm: transitionFormAuthoringMode({
+			config: {
+				id: optionId,
+				...embeddedForm
+			},
+			fieldGroups,
+			preserveSimpleMode
+		})
 	};
 	return withChoiceOptionsOnRawItem(rawItem, options);
 };
@@ -2751,6 +2783,10 @@ const normalizeFormOperationTranslations = (operation, optionId) => ({
 		contentKey: normalizeFormTranslationKey(translation.contentKey.trim(), optionId)
 	}))
 });
+const normalizeEmbeddedFormAuthoringMode = (operation) => ({
+	...operation,
+	form: normalizeFormAuthoringConfig(operation.form) ?? operation.form
+});
 const getItemTranslationText = ({ contentKey, itemId, locale, snapshot }) => {
 	const content = new SurveyTranslations(snapshot.survey.translations).getItemTranslations(itemId)?.getContent(locale, contentKey);
 	return content ? getContentPlainText(content).trim() : void 0;
@@ -2920,7 +2956,7 @@ const getChoiceCreateContentIssue = ({ operation, operationId, operationIndex, i
 	if (missingLabelOptionIds.length === 0) return;
 	return createIssue({
 		code: "missing-choice-option-labels",
-		message: `New choice item options need visible labels. Missing labels for option id(s): ${missingLabelOptionIds.join(", ")}.`,
+		message: `New choice item options need visible labels. Missing labels for option id(s): ${formatBoundedDiagnosticValues(missingLabelOptionIds)}.`,
 		operationIndex,
 		operationId,
 		itemId
@@ -3001,7 +3037,7 @@ const getFormOperationContentIssue = ({ fieldGroups, itemId, operationId, operat
 	if (missingContentKeys.length === 0) return;
 	return createIssue({
 		code: "missing-form-field-content",
-		message: "Introduced form fields and select options need visible labels. Add non-empty translations for: " + missingContentKeys.join(", ") + ".",
+		message: "Introduced form fields and select options need visible labels. Add non-empty translations for: " + formatBoundedDiagnosticValues(missingContentKeys) + ".",
 		operationIndex,
 		operationId,
 		itemId
@@ -3068,6 +3104,7 @@ const getMissingFieldGroupsWrapperHint = (record) => {
 const hasNonEmptyCreateTranslation = (translations, contentKey) => (translations ?? []).some((translation) => translation.contentKey === contentKey && getTranslationPlainText(translation).length > 0);
 const getFormCreateFieldLabelIssue = ({ operation, operationId, operationIndex, itemId }) => {
 	if (operation.item.itemType !== FORM_ITEM_TYPE || !isRecord$2(operation.item.config)) return;
+	if (operation.item.config.authoringMode === "custom" && Array.isArray(operation.item.config.fieldGroups) && operation.item.config.fieldGroups.length === 1 && isRecord$2(operation.item.config.fieldGroups[0]) && Array.isArray(operation.item.config.fieldGroups[0].fields) && operation.item.config.fieldGroups[0].fields.length === 0) return;
 	const wrapperHint = getMissingFieldGroupsWrapperHint(operation.item.config);
 	if (wrapperHint) return createIssue({
 		code: "missing-field-groups-wrapper",
@@ -3084,7 +3121,7 @@ const getFormCreateFieldLabelIssue = ({ operation, operationId, operationIndex,
 	});
 	if (missingSelectOptionLabelContentKeys.length > 0) return createIssue({
 		code: "missing-form-select-option-labels",
-		message: `New form item select options need visible labels. Add translations for: ` + missingSelectOptionLabelContentKeys.join(", ") + ".",
+		message: `New form item select options need visible labels. Add translations for: ` + formatBoundedDiagnosticValues(missingSelectOptionLabelContentKeys) + ".",
 		operationIndex,
 		operationId,
 		itemId
@@ -3092,7 +3129,7 @@ const getFormCreateFieldLabelIssue = ({ operation, operationId, operationIndex,
 	if (missingLabelFieldIds.length === 0) return;
 	return createIssue({
 		code: "missing-form-field-labels",
-		message: `New form item fields need visible labels. Add a translation with contentKey "fields.<fieldId>.label" for field id(s): ${missingLabelFieldIds.join(", ")}.`,
+		message: `New form item fields need visible labels. Add a translation with contentKey "fields.<fieldId>.label" for field id(s): ${formatBoundedDiagnosticValues(missingLabelFieldIds)}.`,
 		operationIndex,
 		operationId,
 		itemId
@@ -3128,7 +3165,7 @@ const getChoiceEmbeddedFormFieldLabelIssue = ({ operation, operationId, operatio
 	if (missingLabelContentKeys.length === 0) return;
 	return createIssue({
 		code: "missing-embedded-form-field-labels",
-		message: `New embedded form fields and select options need visible labels, otherwise respondents only see raw keys. Add translations for: ${missingLabelContentKeys.join(", ")}.`,
+		message: `New embedded form fields and select options need visible labels, otherwise respondents only see raw keys. Add translations for: ${formatBoundedDiagnosticValues(missingLabelContentKeys)}.`,
 		operationIndex,
 		operationId,
 		itemId
@@ -3330,6 +3367,7 @@ const normalizeOperation = (operation, resolvedItemId) => {
 			locale: operation.locale.trim(),
 			contentKey: operation.contentKey.trim()
 		};
+		case "add-survey-locale":
 		case "remove-survey-locale": return {
 			...operation,
 			locale: operation.locale.trim()
@@ -3411,9 +3449,11 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 	const createdKeysByParentId = /* @__PURE__ */ new Map();
 	const plannedKeys = /* @__PURE__ */ new Map();
 	const deletedItemIds = /* @__PURE__ */ new Set();
+	const plannedLocales = new Set(snapshot.inspection.locales);
 	const introducedLocaleWarnings = /* @__PURE__ */ new Set();
 	const addIntroducedLocaleWarning = ({ itemId, locale, operationId, operationIndex }) => {
-		if (snapshot.inspection.locales.includes(locale)) return;
+		if (plannedLocales.has(locale)) return;
+		plannedLocales.add(locale);
 		const warningKey = `${operationIndex}:${itemId ?? ""}:${locale}`;
 		if (introducedLocaleWarnings.has(warningKey)) return;
 		introducedLocaleWarnings.add(warningKey);
@@ -3680,25 +3720,45 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 						return;
 					}
 					break;
-				case "remove-survey-locale":
-					if (!snapshot.inspection.locales.includes(normalized.locale)) {
+				case "add-survey-locale":
+					if (normalized.locale.length === 0) {
 						issues.push(createIssue({
-							code: "survey-locale-not-found",
-							message: `Locale "${normalized.locale}" is not present in the survey.`,
+							code: "invalid-survey-locale",
+							message: "Survey locale cannot be blank.",
+							operationIndex,
+							operationId
+						}));
+						return;
+					}
+					if (plannedLocales.has(normalized.locale)) {
+						issues.push(createIssue({
+							code: "survey-locale-already-exists",
+							message: `Locale "${normalized.locale}" is already present in the survey.`,
 							operationIndex,
 							operationId
 						}));
 						return;
 					}
-					if (snapshot.inspection.locales.length <= 1) {
+					plannedLocales.add(normalized.locale);
+					warnings.push(createIssue({
+						severity: "warning",
+						code: "empty-locale-registration",
+						message: `This operation only registers an empty "${normalized.locale}" locale. It does not complete a request to localize or translate existing respondent-facing content; continue with real translation operations unless the user explicitly requested an empty registration.`,
+						operationIndex,
+						operationId
+					}));
+					break;
+				case "remove-survey-locale":
+					if (!plannedLocales.has(normalized.locale)) {
 						issues.push(createIssue({
-							code: "cannot-remove-last-survey-locale",
-							message: "The survey's final locale cannot be removed.",
+							code: "survey-locale-not-found",
+							message: `Locale "${normalized.locale}" is not present in the survey.`,
 							operationIndex,
 							operationId
 						}));
 						return;
 					}
+					plannedLocales.delete(normalized.locale);
 					break;
 				case "update-image-asset-metadata":
 				case "remove-image-asset":
@@ -3749,7 +3809,7 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 		const normalized = rawNormalized.kind === "update-item-translation" || rawNormalized.kind === "update-placed-image" ? {
 			...rawNormalized,
 			contentKey: normalizeContentKeyForItemType(rawNormalized.contentKey, itemTypeManifestByType.get(rawItem.itemType))
-		} : rawNormalized.kind === "upsert-form-field-group" || rawNormalized.kind === "upsert-form-field" ? normalizeFormOperationTranslations(rawNormalized, rawNormalized.target.optionId) : rawNormalized.kind === "set-embedded-form" ? normalizeFormOperationTranslations(rawNormalized, rawNormalized.optionId) : rawNormalized;
+		} : rawNormalized.kind === "upsert-form-field-group" || rawNormalized.kind === "upsert-form-field" ? normalizeFormOperationTranslations(rawNormalized, rawNormalized.target.optionId) : rawNormalized.kind === "set-embedded-form" ? normalizeEmbeddedFormAuthoringMode(normalizeFormOperationTranslations(rawNormalized, rawNormalized.optionId)) : rawNormalized;
 		if (!itemTypeManifestByType.get(rawItem.itemType)?.supportedOperations.includes(normalized.kind)) {
 			issues.push(createIssue({
 				code: "operation-not-supported-for-item-type",
@@ -4076,7 +4136,12 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 					...existingField,
 					...normalized.field
 				});
-				const nextItem = withFormFieldGroupsForTarget(rawItem, nextGroups, normalized.target.optionId);
+				const nextItem = withFormFieldGroupsForTarget(rawItem, nextGroups, normalized.target.optionId, isCompatibleSimpleFieldUpsert({
+					config: getFormConfigForTarget(rawItem, normalized.target.optionId),
+					groupId: normalized.groupId,
+					field: normalized.field,
+					index: normalized.index
+				}));
 				if (nextItem) rawItemsById.set(item.itemId, nextItem);
 				for (const translation of normalized.translations ?? []) addIntroducedLocaleWarning({
 					locale: translation.locale,
@@ -4453,6 +4518,16 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 					break;
 				}
 				const previousParentId = parentByChildId.get(item.itemId);
+				if (previousParentId === parent.itemId) {
+					issues.push(createIssue({
+						code: "item-already-in-target-parent",
+						message: "The item is already in the target parent. Omit an unchanged placement or use reorder-items with the parent's complete child order.",
+						operationIndex,
+						operationId,
+						itemId: item.itemId
+					}));
+					break;
+				}
 				if (previousParentId) {
 					const previousParent = rawItemsById.get(previousParentId);
 					if (previousParent) rawItemsById.set(previousParentId, {
@@ -4858,7 +4933,12 @@ const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey
 						survey
 					});
 				}
-				replaceItem(withFormFieldGroupsForTarget(item, groups, operation.target.optionId));
+				replaceItem(withFormFieldGroupsForTarget(item, groups, operation.target.optionId, operation.kind === "upsert-form-field" && isCompatibleSimpleFieldUpsert({
+					config: getFormConfigForTarget(item, operation.target.optionId),
+					groupId: operation.groupId,
+					field: operation.field,
+					index: operation.index
+				})));
 				break;
 			}
 			case "remove-item": {
@@ -4935,6 +5015,12 @@ const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey
 				};
 				break;
 			}
+			case "add-survey-locale":
+				survey.translations = {
+					...survey.translations ?? {},
+					[operation.locale]: {}
+				};
+				break;
 			case "remove-survey-locale": {
 				const translations = { ...survey.translations ?? {} };
 				delete translations[operation.locale];
@@ -4990,677 +5076,794 @@ const createSurveyChangeSet = ({ maxOperations, operations, snapshot, summary, t
 	};
 };
 //#endregion
-//#region src/engine/turn-survey-draft.ts
-const createId = () => globalThis.crypto.randomUUID();
-const operationTargets = (operation) => {
-	switch (operation.kind) {
-		case "create-item": return [`item:${operation.item.id}`];
-		case "update-item-key":
-		case "update-item-label":
-		case "update-item-color":
-		case "update-item-translation":
-		case "update-placed-image":
-		case "patch-item-config":
-		case "add-choice-option":
-		case "update-choice-option-label":
-		case "remove-choice-option":
-		case "reorder-choice-options":
-		case "set-embedded-form":
-		case "remove-embedded-form":
-		case "remove-item":
-		case "move-item": return [`item:${operation.itemId}`];
-		case "upsert-form-field-group":
-		case "remove-form-field-group":
-		case "reorder-form-field-groups":
-		case "upsert-form-field":
-		case "remove-form-field":
-		case "move-form-field": return [`item:${operation.target.itemId}`];
-		case "reorder-items": return [`item:${operation.parentItemId}`];
-		case "set-image-asset":
-		case "update-image-asset-metadata":
-		case "remove-image-asset": return [`asset:${operation.assetId}`];
-		case "update-survey-metadata":
-		case "update-survey-pagination":
-		case "update-survey-translation":
-		case "remove-survey-locale": return ["survey"];
-		case "survey-json-patch": return [];
+//#region src/engine/audit.ts
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const records = (value) => Array.isArray(value) ? value.filter(isRecord$1) : [];
+const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+const QUALITY_PRINCIPLES = [
+	{
+		id: "purpose-alignment",
+		title: "Purpose and construct alignment",
+		prompt: "Does every question serve a stated objective, and does it measure the intended construct?"
+	},
+	{
+		id: "cognitive-burden",
+		title: "Respondent burden",
+		prompt: "Is the survey as short and cognitively simple as its purpose allows?"
+	},
+	{
+		id: "question-wording",
+		title: "Clear, neutral wording",
+		prompt: "Are questions specific, neutral, answerable, and limited to one idea without assumptions or double negatives?"
+	},
+	{
+		id: "recall",
+		title: "Recall and reference periods",
+		prompt: "Are recall periods explicit, realistic, and consistent with what respondents can remember?"
+	},
+	{
+		id: "response-options",
+		title: "Response option quality",
+		prompt: "Are options mutually exclusive, collectively sufficient, balanced, ordered, and consistently scaled?"
+	},
+	{
+		id: "flow",
+		title: "Flow and completeness",
+		prompt: "Does the order move logically from easy/general to specific, with needed instructions and no important objective omitted?"
+	},
+	{
+		id: "routing",
+		title: "Requiredness and routing",
+		prompt: "Do required fields, branching, validation, and not-applicable paths avoid forcing inaccurate answers?"
+	},
+	{
+		id: "sensitivity",
+		title: "Sensitivity and ethics",
+		prompt: "Are sensitive questions justified, respectfully phrased, appropriately optional, and paired with privacy context where needed?"
+	},
+	{
+		id: "accessibility",
+		title: "Accessibility and inclusion",
+		prompt: "Is language plain and inclusive, and are content, controls, and images understandable without avoidable barriers?"
+	},
+	{
+		id: "localization",
+		title: "Cross-language equivalence",
+		prompt: "Do translations preserve meaning and cultural relevance rather than merely matching words?"
+	},
+	{
+		id: "testing",
+		title: "Testing and validation",
+		prompt: "Has the instrument been cognitively tested, piloted, and checked for reliability or validity where the intended use requires it?"
 	}
+];
+const translationText = (context, locale, itemId, contentKey) => {
+	const localeTranslations = isRecord$1(context.survey.translations?.[locale]) ? context.survey.translations?.[locale] : void 0;
+	const itemTranslations = isRecord$1(localeTranslations?.itemTranslations) ? localeTranslations.itemTranslations : void 0;
+	const content = (isRecord$1(itemTranslations?.[itemId]) ? itemTranslations[itemId] : void 0)?.[contentKey];
+	return content ? getContentPlainText(content).trim() : "";
 };
-const collectOperationTargets = (operations) => new Set(operations.flatMap(operationTargets));
-/**
-* Request-scoped transactional draft for one assistant response.
-*
-* Mutation tools submit deltas. A successful delta replaces the previous
-* candidate with a newly validated, cumulative change set. A rejected delta
-* leaves the accepted draft intact and blocks authorization until a later
-* delta validates. Only the latest cumulative candidate can be authorized.
-*/
-var TurnSurveyDraft = class {
-	turnId;
-	#candidates = /* @__PURE__ */ new Map();
-	#draftOperations = [];
-	#context;
-	#latestChangeSetId;
-	#unresolvedCandidates = /* @__PURE__ */ new Map();
-	#final = null;
-	constructor(turnId = createId()) {
-		this.turnId = turnId;
-	}
-	initialize(context) {
-		if (this.#context) throw new Error("The survey turn draft was initialized more than once.");
-		this.#context = context;
-	}
-	stage({ addressedTargets = [], operations, snapshot, summary }) {
-		this.#assertOpen();
-		if (!this.#context && snapshot && "document" in snapshot && "trustedCapabilities" in snapshot) this.#context = snapshot;
-		const currentContext = this.#context ?? snapshot;
-		const targets = new Set([...collectOperationTargets(operations), ...addressedTargets]);
-		const delta = createSurveyChangeSet({
-			operations,
-			snapshot: currentContext,
-			summary,
-			turnId: this.turnId
+const getGroups = (item, optionId) => {
+	const config = isRecord$1(item.config) ? item.config : {};
+	if (!optionId) return records(config.fieldGroups);
+	const option = records(config.options).find((entry) => entry.id === optionId);
+	return records(isRecord$1(option?.embeddedForm) ? option.embeddedForm.fieldGroups : void 0);
+};
+const auditSurvey = (context, options = {}) => {
+	const findings = [];
+	const add = (finding) => findings.push(finding);
+	const items = context.survey.surveyItems;
+	const itemsById = /* @__PURE__ */ new Map();
+	const parentById = /* @__PURE__ */ new Map();
+	const itemTypes = {};
+	for (const item of items) {
+		itemTypes[item.itemType] = (itemTypes[item.itemType] ?? 0) + 1;
+		if (itemsById.has(item.id)) add({
+			code: "duplicate-item-id",
+			severity: "error",
+			category: "structure",
+			itemId: item.id,
+			message: `Item id "${item.id}" is duplicated.`
 		});
-		if (delta.status !== "validated" || !delta.validation.valid) return this.reject(delta, targets);
-		const cumulativeOperations = [...this.#draftOperations, ...delta.operations];
-		if (cumulativeOperations.length > 1e3) return this.reject(createSurveyChangeSet({
-			maxOperations: MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT,
-			operations: cumulativeOperations,
-			snapshot: currentContext,
-			summary,
-			turnId: this.turnId
-		}), targets);
-		if (this.#context) {
-			const survey = applyValidatedSurveyOperationsToDraft({
-				operations: delta.operations,
-				survey: this.#context.survey
+		itemsById.set(item.id, item);
+	}
+	for (const parent of items) {
+		const seenChildren = /* @__PURE__ */ new Set();
+		for (const childId of strings(isRecord$1(parent.config) ? parent.config.items : void 0)) {
+			if (seenChildren.has(childId)) add({
+				code: "duplicate-child-reference",
+				severity: "error",
+				category: "structure",
+				itemId: parent.id,
+				message: `Child "${childId}" is listed more than once.`
 			});
-			this.#context = createSurveyAssistantEngineContext({
-				...this.#context.document,
-				survey
-			}, this.#context.trustedCapabilities);
+			seenChildren.add(childId);
+			if (!itemsById.has(childId)) add({
+				code: "missing-child",
+				severity: "error",
+				category: "structure",
+				itemId: parent.id,
+				message: `Referenced child "${childId}" does not exist.`
+			});
+			else if (parentById.has(childId)) add({
+				code: "multiple-parents",
+				severity: "error",
+				category: "structure",
+				itemId: childId,
+				message: `Item is referenced by multiple parents.`
+			});
+			else parentById.set(childId, parent.id);
 		}
-		const registered = surveyChangeSetSchema.parse({
-			...delta,
-			operations: cumulativeOperations,
-			validation: {
-				valid: true,
-				issues: [],
-				warnings: delta.validation.warnings,
-				normalizedOperations: cumulativeOperations
-			},
-			...this.#latestChangeSetId ? { supersedesChangeIds: [this.#latestChangeSetId] } : {}
-		});
-		this.#candidates.set(registered.id, registered);
-		this.#draftOperations = registered.operations;
-		this.#latestChangeSetId = registered.id;
-		for (const [changeSetId, unresolvedTargets] of this.#unresolvedCandidates) if (unresolvedTargets.size === 0 || [...unresolvedTargets].some((target) => targets.has(target))) this.#unresolvedCandidates.delete(changeSetId);
-		return registered;
 	}
-	reject(candidate, addressedTargets = []) {
-		this.#assertOpen();
-		if (this.#candidates.has(candidate.id)) throw new Error(`Survey change "${candidate.id}" was registered more than once.`);
-		const registered = surveyChangeSetSchema.parse({
-			...candidate,
-			turnId: this.turnId,
-			status: "rejected",
-			validation: {
-				...candidate.validation,
-				valid: false
-			}
-		});
-		this.#candidates.set(registered.id, registered);
-		this.#unresolvedCandidates.set(registered.id, new Set(addressedTargets));
-		return registered;
-	}
-	finalize(status, createdAt = (/* @__PURE__ */ new Date()).toISOString()) {
-		if (this.#final) return this.#final;
-		const blockedChangeSetIds = [...this.#unresolvedCandidates.keys()];
-		const canAuthorize = status === "completed" && blockedChangeSetIds.length === 0 && this.#latestChangeSetId !== void 0;
-		this.#final = surveyAssistantTurnFinalSchema.parse({
-			protocolVersion: 1,
-			turnId: this.turnId,
-			status,
-			executableChangeSetIds: canAuthorize ? [this.#latestChangeSetId] : [],
-			...blockedChangeSetIds.length > 0 ? { blockedChangeSetIds } : {},
-			createdAt
-		});
-		return this.#final;
-	}
-	getCandidate(changeSetId) {
-		return this.#candidates.get(changeSetId);
-	}
-	get draftOperations() {
-		return this.#draftOperations;
-	}
-	get context() {
-		return this.#context;
-	}
-	get final() {
-		return this.#final;
-	}
-	#assertOpen() {
-		if (this.#final) throw new Error("Cannot register a survey change after the turn was finalized.");
-	}
-};
-//#endregion
-//#region src/engine/task-context.ts
-const MAX_RELATED_ITEMS = 48;
-const MAX_SIBLING_ITEMS = 80;
-const MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM = 24;
-const MAX_VISIBLE_TEXT_CHARS = 600;
-const MAX_NAMING_EXAMPLES = 40;
-const MAX_TRANSLATION_EXAMPLES = 60;
-const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const getItemLabel = (item) => {
-	if (!isRecord$1(item.metadata)) return void 0;
-	const label = item.metadata.itemLabel;
-	return typeof label === "string" && label.trim().length > 0 ? label.trim() : void 0;
-};
-const getCenteredNeighbors = (values, focusIndex, limit) => {
-	if (focusIndex < 0 || limit < 1) return [];
-	const windowSize = Math.min(values.length, limit + 1);
-	const idealStart = focusIndex - Math.floor(limit / 2);
-	const start = Math.min(Math.max(0, idealStart), values.length - windowSize);
-	return values.slice(start, start + windowSize).filter((_, index) => start + index !== focusIndex);
-};
-const buildSurveyAssistantTaskContext = (snapshot, options) => {
-	const { inspection } = createSurveyAssistantEngineContext(snapshot, void 0, { focusItemId: options.focusItemId });
-	const itemsById = new Map(snapshot.survey.surveyItems.map((item) => [item.id, item]));
-	const parentById = new Map(inspection.outline.flatMap((item) => item.parentId ? [[item.itemId, item.parentId]] : []));
-	const childIdsByParent = /* @__PURE__ */ new Map();
-	for (const item of inspection.outline) {
-		if (!item.parentId) continue;
-		const childIds = childIdsByParent.get(item.parentId) ?? [];
-		childIds.push(item.itemId);
-		childIdsByParent.set(item.parentId, childIds);
-	}
-	const fullKeyById = new Map(inspection.keyIndex.map((item) => [item.itemId, item.fullKey]));
-	const summarizeItem = (item) => {
-		const allVisibleText = [];
-		let visibleTextValueTruncated = false;
-		for (const [locale, translations] of Object.entries(snapshot.survey.translations ?? {})) {
-			const itemTranslations = translations.itemTranslations?.[item.id];
-			if (!itemTranslations) continue;
-			for (const [contentKey, content] of Object.entries(itemTranslations)) {
-				const text = getContentPlainText(content).trim();
-				if (text) {
-					if (text.length > MAX_VISIBLE_TEXT_CHARS) visibleTextValueTruncated = true;
-					allVisibleText.push({
-						locale,
-						contentKey,
-						text: text.length > MAX_VISIBLE_TEXT_CHARS ? `${text.slice(0, MAX_VISIBLE_TEXT_CHARS)}...` : text
-					});
-				}
-			}
-		}
-		return {
-			id: item.id,
-			key: item.key,
-			fullKey: fullKeyById.get(item.id) ?? item.key,
-			itemType: item.itemType,
-			itemLabel: getItemLabel(item),
-			visibleText: allVisibleText.slice(0, MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM),
-			visibleTextTruncated: allVisibleText.length > MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM || visibleTextValueTruncated
-		};
-	};
-	const rootItemId = inspection.outline.find((item) => item.depth === 0)?.itemId;
-	const rootItem = rootItemId ? itemsById.get(rootItemId) : void 0;
-	const result = {
-		document: {
-			revision: snapshot.version.revision,
-			contentHash: snapshot.version.contentHash,
-			capabilityDigest: snapshot.version.capabilityDigest
-		},
-		survey: {
-			key: rootItem?.key,
-			locales: inspection.locales,
-			itemCount: inspection.itemCount,
-			selectedLocale: snapshot.ui.selectedLocale
-		}
-	};
-	const focusItem = options.focusItemId ? itemsById.get(options.focusItemId) : void 0;
-	if (focusItem) {
-		const parentId = parentById.get(focusItem.id);
-		const parentItem = parentId ? itemsById.get(parentId) : void 0;
-		const ancestorItems = [];
-		const seenAncestorIds = /* @__PURE__ */ new Set();
-		let ancestorId = parentId;
-		while (ancestorId && !seenAncestorIds.has(ancestorId)) {
-			seenAncestorIds.add(ancestorId);
-			const ancestor = itemsById.get(ancestorId);
-			if (!ancestor) break;
-			ancestorItems.unshift(ancestor);
-			ancestorId = parentById.get(ancestorId);
-		}
-		const siblingIds = parentItem ? childIdsByParent.get(parentItem.id) ?? [] : [];
-		const siblingItemCount = Math.max(0, siblingIds.length - 1);
-		const siblingItems = getCenteredNeighbors(siblingIds, siblingIds.indexOf(focusItem.id), MAX_SIBLING_ITEMS).map((itemId) => itemsById.get(itemId)).filter((item) => Boolean(item));
-		const allRelatedItems = [];
-		const seenRelatedIds = /* @__PURE__ */ new Set();
-		const pending = [...childIdsByParent.get(focusItem.id) ?? []];
-		while (pending.length > 0) {
-			const itemId = pending.shift();
-			const item = itemId ? itemsById.get(itemId) : void 0;
-			if (!item || seenRelatedIds.has(item.id)) continue;
-			seenRelatedIds.add(item.id);
-			allRelatedItems.push(item);
-			pending.push(...childIdsByParent.get(item.id) ?? []);
+	const roots = items.filter((item) => !parentById.has(item.id));
+	if (roots.length !== 1) add({
+		code: "root-count",
+		severity: "error",
+		category: "structure",
+		message: `Expected one survey root but found ${roots.length}.`
+	});
+	for (const parent of items) {
+		const siblingKeys = /* @__PURE__ */ new Map();
+		for (const childId of strings(isRecord$1(parent.config) ? parent.config.items : void 0)) {
+			const child = itemsById.get(childId);
+			if (!child) continue;
+			const existing = siblingKeys.get(child.key);
+			if (existing) add({
+				code: "duplicate-sibling-key",
+				severity: "error",
+				category: "structure",
+				itemId: child.id,
+				message: `Key "${child.key}" duplicates sibling "${existing}".`
+			});
+			siblingKeys.set(child.key, child.id);
 		}
-		const relatedItems = allRelatedItems.slice(0, MAX_RELATED_ITEMS);
-		result.focus = {
-			item: summarizeItem(focusItem),
-			parent: parentItem ? summarizeItem(parentItem) : void 0,
-			ancestorPath: ancestorItems.map(summarizeItem),
-			siblingKeys: siblingItems.map((item) => item.key),
-			siblingItems: siblingItems.map(summarizeItem),
-			siblingItemCount,
-			siblingItemsTruncated: siblingItemCount > siblingItems.length,
-			relatedItems: relatedItems.map(summarizeItem),
-			relatedItemCount: allRelatedItems.length,
-			relatedItemsTruncated: allRelatedItems.length > relatedItems.length
-		};
 	}
-	if ((options.purpose === "suggest-item-key" || options.purpose === "suggest-item-label") && focusItem) {
-		const parentId = parentById.get(focusItem.id);
-		const siblingIds = parentId ? childIdsByParent.get(parentId) ?? [] : [];
-		const siblingPositionById = new Map(siblingIds.map((itemId, index) => [itemId, index]));
-		const focusSiblingPosition = siblingPositionById.get(focusItem.id);
-		const rankedItems = snapshot.survey.surveyItems.filter((item) => item.id !== focusItem.id).map((item, index) => ({
-			item,
-			index,
-			siblingDistance: focusSiblingPosition !== void 0 && siblingPositionById.has(item.id) ? Math.abs(siblingPositionById.get(item.id) - focusSiblingPosition) : Number.POSITIVE_INFINITY,
-			relationship: parentById.get(item.id) === parentId ? "sibling" : item.itemType === focusItem.itemType ? "same-type" : "survey"
-		})).sort((left, right) => {
-			const rank = {
-				sibling: 0,
-				"same-type": 1,
-				survey: 2
-			};
-			return rank[left.relationship] - rank[right.relationship] || left.siblingDistance - right.siblingDistance || left.index - right.index;
-		});
-		const allKeyExamples = rankedItems.map(({ item, relationship }) => ({
-			itemId: item.id,
-			itemType: item.itemType,
-			key: item.key,
-			relationship
-		}));
-		const allLabelExamples = rankedItems.flatMap(({ item, relationship }) => {
-			const label = getItemLabel(item);
-			return label ? [{
+	const locales = context.inspection.locales;
+	const sourceLocale = options.sourceLocale ?? context.ui.selectedLocale ?? locales[0];
+	const targetLocales = options.targetLocales ?? locales.filter((locale) => locale !== sourceLocale);
+	const manifests = new Map(context.capabilities.itemTypes.map((entry) => [entry.itemType, entry]));
+	for (const item of items) {
+		const manifest = manifests.get(item.itemType);
+		if (!manifest) {
+			add({
+				code: "unsupported-item-type",
+				severity: "warning",
+				category: "structure",
 				itemId: item.id,
-				itemType: item.itemType,
-				key: item.key,
-				label,
-				relationship
-			}] : [];
+				message: `Item type "${item.itemType}" is not advertised by the active editor.`
+			});
+			continue;
+		}
+		for (const surface of manifest.contentSurfaces.filter((entry) => entry.requiredOnCreate && !entry.pattern)) if (!translationText(context, sourceLocale, item.id, surface.key)) add({
+			code: "missing-primary-content",
+			severity: "warning",
+			category: "content",
+			itemId: item.id,
+			locale: sourceLocale,
+			contentKey: surface.key,
+			message: `Required respondent content "${surface.key}" is empty in ${sourceLocale}.`
 		});
-		result.naming = {
-			keyExamples: allKeyExamples.slice(0, MAX_NAMING_EXAMPLES),
-			keyExampleCount: allKeyExamples.length,
-			keyExamplesTruncated: allKeyExamples.length > MAX_NAMING_EXAMPLES,
-			labelExamples: allLabelExamples.slice(0, MAX_NAMING_EXAMPLES),
-			labelExampleCount: allLabelExamples.length,
-			labelExamplesTruncated: allLabelExamples.length > MAX_NAMING_EXAMPLES
-		};
-	}
-	const sourceLocale = options.sourceLocale;
-	if (options.purpose === "translate-content" && sourceLocale) {
-		const relevantLocales = [sourceLocale, ...options.targetLocales ?? []];
-		const sourceTokens = new Set((options.sourceTexts ?? []).flatMap((text) => text.toLocaleLowerCase().split(/[^\p{L}\p{N}]+/u)).filter((token) => token.length >= 3));
-		const allExamples = [];
-		snapshot.survey.surveyItems.forEach((item, itemIndex) => {
-			const contentKeys = /* @__PURE__ */ new Set();
-			for (const locale of relevantLocales) {
-				const itemTranslations = snapshot.survey.translations?.[locale]?.itemTranslations?.[item.id];
-				for (const contentKey of Object.keys(itemTranslations ?? {})) contentKeys.add(contentKey);
-			}
-			for (const contentKey of contentKeys) {
-				const values = {};
-				for (const locale of relevantLocales) {
-					const content = snapshot.survey.translations?.[locale]?.itemTranslations?.[item.id]?.[contentKey];
-					if (!content) continue;
-					const text = getContentPlainText(content).trim();
-					if (text) values[locale] = text.slice(0, MAX_VISIBLE_TEXT_CHARS);
-				}
-				const sourceText = values[sourceLocale];
-				if (!sourceText || Object.keys(values).length < 2) continue;
-				const normalizedSource = sourceText.toLocaleLowerCase();
-				const score = [...sourceTokens].reduce((total, token) => total + (normalizedSource.includes(token) ? 1 : 0), 0);
-				allExamples.push({
+		const sourceContent = isRecord$1(context.survey.translations?.[sourceLocale]?.itemTranslations?.[item.id]) ? context.survey.translations?.[sourceLocale]?.itemTranslations?.[item.id] : {};
+		for (const [contentKey, content] of Object.entries(sourceContent ?? {})) {
+			if (!getContentPlainText(content).trim()) continue;
+			for (const locale of targetLocales) if (!translationText(context, locale, item.id, contentKey)) add({
+				code: "missing-translation",
+				severity: "warning",
+				category: "localization",
+				itemId: item.id,
+				locale,
+				contentKey,
+				message: `Content "${contentKey}" has source text but no ${locale} translation.`
+			});
+		}
+		const config = isRecord$1(item.config) ? item.config : {};
+		if (item.itemType === "choiceItem") {
+			const optionsList = records(config.options);
+			if (optionsList.length === 0) add({
+				code: "choice-without-options",
+				severity: "error",
+				category: "content",
+				itemId: item.id,
+				message: "Choice item has no options."
+			});
+			for (const option of optionsList) {
+				if (typeof option.id === "string" && !translationText(context, sourceLocale, item.id, `options.${option.id}.label`)) add({
+					code: "missing-option-label",
+					severity: "warning",
+					category: "content",
 					itemId: item.id,
-					contentKey,
-					values,
-					score,
-					order: itemIndex
+					locale: sourceLocale,
+					contentKey: `options.${option.id}.label`,
+					message: `Choice option "${option.id}" has no visible label.`
 				});
+				if (typeof option.id === "string" && option.embeddedForm) {
+					for (const group of getGroups(item, option.id)) for (const field of records(group.fields)) if (typeof field.id === "string" && !translationText(context, sourceLocale, item.id, `embeddedForms.${option.id}.fields.${field.id}.label`)) add({
+						code: "missing-field-label",
+						severity: "warning",
+						category: "content",
+						itemId: item.id,
+						locale: sourceLocale,
+						contentKey: `embeddedForms.${option.id}.fields.${field.id}.label`,
+						message: `Embedded field "${field.id}" has no visible label.`
+					});
+				}
 			}
+		}
+		if (item.itemType === "formItem") {
+			const groups = getGroups(item);
+			if (groups.length === 0) add({
+				code: "form-without-groups",
+				severity: "error",
+				category: "content",
+				itemId: item.id,
+				message: "Form item has no field groups."
+			});
+			for (const group of groups) for (const field of records(group.fields)) if (typeof field.id === "string" && !translationText(context, sourceLocale, item.id, `fields.${field.id}.label`)) add({
+				code: "missing-field-label",
+				severity: "warning",
+				category: "content",
+				itemId: item.id,
+				locale: sourceLocale,
+				contentKey: `fields.${field.id}.label`,
+				message: `Form field "${field.id}" has no visible label.`
+			});
+		}
+	}
+	const assets = context.survey.assets ?? {};
+	for (const [assetId, asset] of Object.entries(assets)) {
+		const metadata = isRecord$1(asset.metadata) ? asset.metadata : {};
+		if (asset.kind === "image" && typeof metadata.alt !== "string") add({
+			code: "missing-image-alt",
+			severity: "warning",
+			category: "assets",
+			message: `Image asset "${assetId}" has no alternative text.`,
+			suggestion: "Add concise alt text, or an empty alt value when the image is purely decorative."
 		});
-		allExamples.sort((left, right) => right.score - left.score || left.order - right.order);
-		result.translation = {
-			examples: allExamples.slice(0, MAX_TRANSLATION_EXAMPLES).map(({ itemId, contentKey, values }) => ({
-				itemId,
-				contentKey,
-				values
-			})),
-			exampleCount: allExamples.length,
-			examplesTruncated: allExamples.length > MAX_TRANSLATION_EXAMPLES
-		};
 	}
-	return result;
+	const limited = findings.slice(0, options.maxFindings ?? 200);
+	return {
+		summary: findings.reduce((acc, entry) => {
+			acc[entry.severity] += 1;
+			acc.total += 1;
+			return acc;
+		}, {
+			error: 0,
+			warning: 0,
+			info: 0,
+			total: 0
+		}),
+		findingCount: findings.length,
+		truncated: limited.length < findings.length,
+		metrics: {
+			itemCount: context.inspection.itemCount,
+			localeCount: locales.length,
+			responseSlotCount: context.inspection.responseSlots.length,
+			assetCount: Object.keys(assets).length,
+			itemTypes
+		},
+		findings: limited,
+		qualityReviewPrinciples: QUALITY_PRINCIPLES,
+		note: "Technical findings are deterministic. Quality principles are a structured review rubric; apply them with human/model judgment and domain context, and do not present them as psychometric validation."
+	};
 };
 //#endregion
-//#region src/engine/task-result-cache.ts
-const DEFAULT_TTL_MS = 900 * 1e3;
-const DEFAULT_MAX_ENTRIES = 64;
-/** Small in-memory LRU cache for deterministic, snapshot-scoped one-shot results. */
-var SurveyAssistantTaskResultCache = class {
-	entries = /* @__PURE__ */ new Map();
-	ttlMs;
-	maxEntries;
-	now;
-	constructor(options = {}) {
-		this.ttlMs = Math.max(0, options.ttlMs ?? DEFAULT_TTL_MS);
-		this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
-		this.now = options.now ?? Date.now;
+//#region src/engine/turn-survey-draft.ts
+const createId = () => globalThis.crypto.randomUUID();
+const operationTargets = (operation) => {
+	switch (operation.kind) {
+		case "create-item": return [`item:${operation.item.id}`];
+		case "update-item-key":
+		case "update-item-label":
+		case "update-item-color":
+		case "update-item-translation":
+		case "update-placed-image":
+		case "patch-item-config":
+		case "add-choice-option":
+		case "update-choice-option-label":
+		case "remove-choice-option":
+		case "reorder-choice-options":
+		case "set-embedded-form":
+		case "remove-embedded-form":
+		case "remove-item":
+		case "move-item": return [`item:${operation.itemId}`];
+		case "upsert-form-field-group":
+		case "remove-form-field-group":
+		case "reorder-form-field-groups":
+		case "upsert-form-field":
+		case "remove-form-field":
+		case "move-form-field": return [`item:${operation.target.itemId}`];
+		case "reorder-items": return [`item:${operation.parentItemId}`];
+		case "set-image-asset":
+		case "update-image-asset-metadata":
+		case "remove-image-asset": return [`asset:${operation.assetId}`];
+		case "update-survey-metadata":
+		case "update-survey-pagination":
+		case "update-survey-translation":
+		case "add-survey-locale":
+		case "remove-survey-locale": return ["survey"];
+		case "survey-json-patch": return operation.patches.map((patch) => `path:${patch.path}`);
 	}
-	get(key) {
-		const entry = this.entries.get(key);
-		if (!entry) return void 0;
-		if (entry.expiresAt <= this.now()) {
-			this.entries.delete(key);
-			return;
+};
+const collectOperationTargets = (operations) => new Set(operations.flatMap(operationTargets));
+const MAX_POST_CHANGE_TARGETS = 16;
+const MAX_POST_CHANGE_ITEMS = 6;
+const MAX_POST_CHANGE_TRANSLATIONS = 12;
+const MAX_POST_CHANGE_RESPONSE_SLOTS = 12;
+const MAX_POST_CHANGE_TEXT_CHARS = 100;
+const MAX_VERIFICATION_AUDIT_FINDINGS = 8;
+const MAX_VERIFICATION_MESSAGE_CHARS = 240;
+const SUBSTANTIAL_CHANGE_ITEM_COUNT = 6;
+const SUBSTANTIAL_CHANGE_OPERATION_COUNT = 12;
+const createPostChangeProjection = (context, targets) => {
+	const allTargets = [...targets];
+	const requestedItemIds = allTargets.filter((target) => target.startsWith("item:")).map((target) => target.slice(5));
+	const itemEntries = requestedItemIds.map((itemId) => context.inspection.keyIndex.find((entry) => entry.itemId === itemId)).filter((entry) => entry !== void 0);
+	const surveyTranslations = new SurveyTranslations(context.survey.translations);
+	let truncated = allTargets.length > MAX_POST_CHANGE_TARGETS || itemEntries.length > MAX_POST_CHANGE_ITEMS;
+	const touchedItems = itemEntries.slice(0, MAX_POST_CHANGE_ITEMS).map((entry) => {
+		const itemTranslations = surveyTranslations.getItemTranslations(entry.itemId);
+		const allTranslations = (itemTranslations?.locales ?? []).flatMap((locale) => Object.entries(itemTranslations?.getAllForLocale(locale) ?? {}).map(([contentKey, content]) => {
+			const textCharacters = [...getContentPlainText(content)];
+			return {
+				locale,
+				contentKey,
+				textPreview: textCharacters.slice(0, MAX_POST_CHANGE_TEXT_CHARS).join(""),
+				textLength: textCharacters.length,
+				truncated: textCharacters.length > MAX_POST_CHANGE_TEXT_CHARS
+			};
+		}));
+		const translations = allTranslations.slice(0, MAX_POST_CHANGE_TRANSLATIONS);
+		const allResponseSlots = Object.keys(context.responseSlotTypes).filter((slot) => slot.startsWith(`${entry.itemId}...`));
+		const responseSlots = allResponseSlots.slice(0, MAX_POST_CHANGE_RESPONSE_SLOTS);
+		if (allTranslations.length > translations.length || allResponseSlots.length > responseSlots.length || translations.some((translation) => translation.truncated)) truncated = true;
+		return {
+			itemId: entry.itemId,
+			itemType: entry.itemType,
+			key: entry.key,
+			fullKey: entry.fullKey,
+			...entry.itemLabel ? { itemLabel: entry.itemLabel } : {},
+			translationCount: allTranslations.length,
+			translations,
+			responseSlotCount: allResponseSlots.length,
+			responseSlots
+		};
+	});
+	return {
+		version: context.version,
+		itemCount: context.inspection.itemCount,
+		localeCount: context.inspection.locales.length,
+		locales: context.inspection.locales.slice(0, 32),
+		targetCount: allTargets.length,
+		touchedTargets: allTargets.slice(0, MAX_POST_CHANGE_TARGETS),
+		touchedItemCount: requestedItemIds.length,
+		availableTouchedItemCount: itemEntries.length,
+		touchedItems,
+		truncated: truncated || context.inspection.locales.length > 32
+	};
+};
+const auditFindingKey = (finding) => [
+	finding.code,
+	finding.category,
+	finding.itemId ?? "",
+	finding.locale ?? "",
+	finding.contentKey ?? ""
+].join("\0");
+const isComplexOperation = (operation) => {
+	if (operation.kind === "survey-json-patch" || operation.kind === "patch-item-config") return true;
+	if (operation.kind !== "create-item") return false;
+	return Boolean(operation.item.displayConditions || operation.item.disabledConditions || operation.item.validations || operation.item.prefills);
+};
+const createChangeVerification = ({ after, before, operations, postChange }) => {
+	const beforeFindingKeys = new Set(auditSurvey(before, { maxFindings: 1e4 }).findings.map(auditFindingKey));
+	const newAuditFindings = auditSurvey(after, { maxFindings: 1e4 }).findings.filter((finding) => !beforeFindingKeys.has(auditFindingKey(finding)));
+	const reasons = [];
+	if (operations.length > SUBSTANTIAL_CHANGE_OPERATION_COUNT || postChange.touchedItemCount > SUBSTANTIAL_CHANGE_ITEM_COUNT) reasons.push("substantial-change");
+	if (operations.some(isComplexOperation)) reasons.push("complex-change");
+	if (postChange.truncated) reasons.push("bounded-preview");
+	if (newAuditFindings.length > 0) reasons.push("new-audit-findings");
+	if (reasons.length === 0) return void 0;
+	let truncated = newAuditFindings.length > MAX_VERIFICATION_AUDIT_FINDINGS;
+	const auditFindings = newAuditFindings.slice(0, MAX_VERIFICATION_AUDIT_FINDINGS).map((finding) => {
+		const messageCharacters = [...finding.message];
+		const messagePreview = messageCharacters.slice(0, MAX_VERIFICATION_MESSAGE_CHARS).join("");
+		const messageTruncated = messageCharacters.length > MAX_VERIFICATION_MESSAGE_CHARS;
+		if (messageTruncated) truncated = true;
+		return {
+			code: finding.code,
+			severity: finding.severity,
+			category: finding.category,
+			...finding.itemId ? { itemId: finding.itemId } : {},
+			...finding.locale ? { locale: finding.locale } : {},
+			...finding.contentKey ? { contentKey: finding.contentKey } : {},
+			messagePreview,
+			messageLength: messageCharacters.length,
+			truncated: messageTruncated
+		};
+	});
+	return {
+		required: true,
+		reasons,
+		newAuditFindingCount: newAuditFindings.length,
+		auditFindings,
+		truncated
+	};
+};
+/**
+* Request-scoped transactional draft for one assistant response.
+*
+* Mutation tools submit deltas. A successful delta replaces the previous
+* candidate with a newly validated, cumulative change set. A rejected delta
+* leaves the accepted draft intact and blocks authorization until a later
+* delta validates. Only the latest cumulative candidate can be authorized.
+*/
+var TurnSurveyDraft = class {
+	turnId;
+	#candidates = /* @__PURE__ */ new Map();
+	#draftOperations = [];
+	#context;
+	#latestChangeSetId;
+	#unresolvedCandidates = /* @__PURE__ */ new Map();
+	#final = null;
+	constructor(turnId = createId()) {
+		this.turnId = turnId;
+	}
+	initialize(context) {
+		if (this.#context) throw new Error("The survey turn draft was initialized more than once.");
+		this.#context = context;
+	}
+	stage({ addressedTargets = [], operations, snapshot, summary }) {
+		this.#assertOpen();
+		if (!this.#context && snapshot && "document" in snapshot && "trustedCapabilities" in snapshot) this.#context = snapshot;
+		const currentContext = this.#context ?? snapshot;
+		const targets = new Set([...collectOperationTargets(operations), ...addressedTargets]);
+		const delta = createSurveyChangeSet({
+			operations,
+			snapshot: currentContext,
+			summary,
+			turnId: this.turnId
+		});
+		if (delta.status !== "validated" || !delta.validation.valid) return this.reject(delta, targets);
+		const cumulativeOperations = [...this.#draftOperations, ...delta.operations];
+		if (cumulativeOperations.length > 1e3) return this.reject(createSurveyChangeSet({
+			maxOperations: MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT,
+			operations: cumulativeOperations,
+			snapshot: currentContext,
+			summary,
+			turnId: this.turnId
+		}), targets);
+		const beforeContext = this.#context;
+		if (this.#context) {
+			const survey = applyValidatedSurveyOperationsToDraft({
+				operations: delta.operations,
+				survey: this.#context.survey
+			});
+			this.#context = createSurveyAssistantEngineContext({
+				...this.#context.document,
+				survey
+			}, this.#context.trustedCapabilities);
 		}
-		this.entries.delete(key);
-		this.entries.set(key, entry);
-		return entry.value;
+		const postChange = this.#context ? createPostChangeProjection(this.#context, targets) : void 0;
+		const verification = beforeContext && this.#context && postChange ? createChangeVerification({
+			after: this.#context,
+			before: beforeContext,
+			operations: delta.operations,
+			postChange
+		}) : void 0;
+		const registered = surveyChangeSetSchema.parse({
+			...delta,
+			operations: cumulativeOperations,
+			...postChange ? { postChange } : {},
+			...verification ? { verification } : {},
+			validation: {
+				valid: true,
+				issues: [],
+				warnings: delta.validation.warnings,
+				normalizedOperations: cumulativeOperations
+			},
+			...this.#latestChangeSetId ? { supersedesChangeIds: [this.#latestChangeSetId] } : {}
+		});
+		this.#candidates.set(registered.id, registered);
+		this.#draftOperations = registered.operations;
+		this.#latestChangeSetId = registered.id;
+		for (const [changeSetId, unresolvedTargets] of this.#unresolvedCandidates) if (unresolvedTargets.size === 0 || [...unresolvedTargets].some((target) => targets.has(target))) this.#unresolvedCandidates.delete(changeSetId);
+		return registered;
+	}
+	reject(candidate, addressedTargets = []) {
+		this.#assertOpen();
+		if (this.#candidates.has(candidate.id)) throw new Error(`Survey change "${candidate.id}" was registered more than once.`);
+		const registered = surveyChangeSetSchema.parse({
+			...candidate,
+			turnId: this.turnId,
+			status: "rejected",
+			validation: {
+				...candidate.validation,
+				valid: false
+			}
+		});
+		this.#candidates.set(registered.id, registered);
+		this.#unresolvedCandidates.set(registered.id, new Set(addressedTargets));
+		return registered;
 	}
-	set(key, value) {
-		this.entries.delete(key);
-		this.entries.set(key, {
-			expiresAt: this.now() + this.ttlMs,
-			value
+	finalize(status, createdAt = (/* @__PURE__ */ new Date()).toISOString(), details = {}) {
+		if (this.#final) return this.#final;
+		const blockedChangeSetIds = [...this.#unresolvedCandidates.keys()];
+		const canAuthorize = status === "completed" && blockedChangeSetIds.length === 0 && this.#latestChangeSetId !== void 0;
+		this.#final = surveyAssistantTurnFinalSchema.parse({
+			protocolVersion: 1,
+			turnId: this.turnId,
+			status,
+			executableChangeSetIds: canAuthorize ? [this.#latestChangeSetId] : [],
+			...blockedChangeSetIds.length > 0 ? { blockedChangeSetIds } : {},
+			...details,
+			createdAt
 		});
-		while (this.entries.size > this.maxEntries) {
-			const oldestKey = this.entries.keys().next().value;
-			if (oldestKey === void 0) break;
-			this.entries.delete(oldestKey);
-		}
+		return this.#final;
 	}
-	clear() {
-		this.entries.clear();
+	getCandidate(changeSetId) {
+		return this.#candidates.get(changeSetId);
+	}
+	get draftOperations() {
+		return this.#draftOperations;
+	}
+	get context() {
+		return this.#context;
+	}
+	get final() {
+		return this.#final;
+	}
+	#assertOpen() {
+		if (this.#final) throw new Error("Cannot register a survey change after the turn was finalized.");
 	}
 };
 //#endregion
-//#region src/engine/audit.ts
+//#region src/engine/task-context.ts
+const MAX_RELATED_ITEMS = 48;
+const MAX_SIBLING_ITEMS = 80;
+const MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM = 24;
+const MAX_VISIBLE_TEXT_CHARS = 600;
+const MAX_NAMING_EXAMPLES = 40;
+const MAX_TRANSLATION_EXAMPLES = 60;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const records = (value) => Array.isArray(value) ? value.filter(isRecord) : [];
-const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-const QUALITY_PRINCIPLES = [
-	{
-		id: "purpose-alignment",
-		title: "Purpose and construct alignment",
-		prompt: "Does every question serve a stated objective, and does it measure the intended construct?"
-	},
-	{
-		id: "cognitive-burden",
-		title: "Respondent burden",
-		prompt: "Is the survey as short and cognitively simple as its purpose allows?"
-	},
-	{
-		id: "question-wording",
-		title: "Clear, neutral wording",
-		prompt: "Are questions specific, neutral, answerable, and limited to one idea without assumptions or double negatives?"
-	},
-	{
-		id: "recall",
-		title: "Recall and reference periods",
-		prompt: "Are recall periods explicit, realistic, and consistent with what respondents can remember?"
-	},
-	{
-		id: "response-options",
-		title: "Response option quality",
-		prompt: "Are options mutually exclusive, collectively sufficient, balanced, ordered, and consistently scaled?"
-	},
-	{
-		id: "flow",
-		title: "Flow and completeness",
-		prompt: "Does the order move logically from easy/general to specific, with needed instructions and no important objective omitted?"
-	},
-	{
-		id: "routing",
-		title: "Requiredness and routing",
-		prompt: "Do required fields, branching, validation, and not-applicable paths avoid forcing inaccurate answers?"
-	},
-	{
-		id: "sensitivity",
-		title: "Sensitivity and ethics",
-		prompt: "Are sensitive questions justified, respectfully phrased, appropriately optional, and paired with privacy context where needed?"
-	},
-	{
-		id: "accessibility",
-		title: "Accessibility and inclusion",
-		prompt: "Is language plain and inclusive, and are content, controls, and images understandable without avoidable barriers?"
-	},
-	{
-		id: "localization",
-		title: "Cross-language equivalence",
-		prompt: "Do translations preserve meaning and cultural relevance rather than merely matching words?"
-	},
-	{
-		id: "testing",
-		title: "Testing and validation",
-		prompt: "Has the instrument been cognitively tested, piloted, and checked for reliability or validity where the intended use requires it?"
-	}
-];
-const translationText = (context, locale, itemId, contentKey) => {
-	const localeTranslations = isRecord(context.survey.translations?.[locale]) ? context.survey.translations?.[locale] : void 0;
-	const itemTranslations = isRecord(localeTranslations?.itemTranslations) ? localeTranslations.itemTranslations : void 0;
-	const content = (isRecord(itemTranslations?.[itemId]) ? itemTranslations[itemId] : void 0)?.[contentKey];
-	return content ? getContentPlainText(content).trim() : "";
+const getItemLabel = (item) => {
+	if (!isRecord(item.metadata)) return void 0;
+	const label = item.metadata.itemLabel;
+	return typeof label === "string" && label.trim().length > 0 ? label.trim() : void 0;
 };
-const getGroups = (item, optionId) => {
-	const config = isRecord(item.config) ? item.config : {};
-	if (!optionId) return records(config.fieldGroups);
-	const option = records(config.options).find((entry) => entry.id === optionId);
-	return records(isRecord(option?.embeddedForm) ? option.embeddedForm.fieldGroups : void 0);
+const getCenteredNeighbors = (values, focusIndex, limit) => {
+	if (focusIndex < 0 || limit < 1) return [];
+	const windowSize = Math.min(values.length, limit + 1);
+	const idealStart = focusIndex - Math.floor(limit / 2);
+	const start = Math.min(Math.max(0, idealStart), values.length - windowSize);
+	return values.slice(start, start + windowSize).filter((_, index) => start + index !== focusIndex);
 };
-const auditSurvey = (context, options = {}) => {
-	const findings = [];
-	const add = (finding) => findings.push(finding);
-	const items = context.survey.surveyItems;
-	const itemsById = /* @__PURE__ */ new Map();
-	const parentById = /* @__PURE__ */ new Map();
-	const itemTypes = {};
-	for (const item of items) {
-		itemTypes[item.itemType] = (itemTypes[item.itemType] ?? 0) + 1;
-		if (itemsById.has(item.id)) add({
-			code: "duplicate-item-id",
-			severity: "error",
-			category: "structure",
-			itemId: item.id,
-			message: `Item id "${item.id}" is duplicated.`
-		});
-		itemsById.set(item.id, item);
+const buildSurveyAssistantTaskContext = (snapshot, options) => {
+	const { inspection } = createSurveyAssistantEngineContext(snapshot, void 0, { focusItemId: options.focusItemId });
+	const itemsById = new Map(snapshot.survey.surveyItems.map((item) => [item.id, item]));
+	const parentById = new Map(inspection.outline.flatMap((item) => item.parentId ? [[item.itemId, item.parentId]] : []));
+	const childIdsByParent = /* @__PURE__ */ new Map();
+	for (const item of inspection.outline) {
+		if (!item.parentId) continue;
+		const childIds = childIdsByParent.get(item.parentId) ?? [];
+		childIds.push(item.itemId);
+		childIdsByParent.set(item.parentId, childIds);
 	}
-	for (const parent of items) {
-		const seenChildren = /* @__PURE__ */ new Set();
-		for (const childId of strings(isRecord(parent.config) ? parent.config.items : void 0)) {
-			if (seenChildren.has(childId)) add({
-				code: "duplicate-child-reference",
-				severity: "error",
-				category: "structure",
-				itemId: parent.id,
-				message: `Child "${childId}" is listed more than once.`
-			});
-			seenChildren.add(childId);
-			if (!itemsById.has(childId)) add({
-				code: "missing-child",
-				severity: "error",
-				category: "structure",
-				itemId: parent.id,
-				message: `Referenced child "${childId}" does not exist.`
-			});
-			else if (parentById.has(childId)) add({
-				code: "multiple-parents",
-				severity: "error",
-				category: "structure",
-				itemId: childId,
-				message: `Item is referenced by multiple parents.`
-			});
-			else parentById.set(childId, parent.id);
+	const fullKeyById = new Map(inspection.keyIndex.map((item) => [item.itemId, item.fullKey]));
+	const summarizeItem = (item) => {
+		const allVisibleText = [];
+		let visibleTextValueTruncated = false;
+		for (const [locale, translations] of Object.entries(snapshot.survey.translations ?? {})) {
+			const itemTranslations = translations.itemTranslations?.[item.id];
+			if (!itemTranslations) continue;
+			for (const [contentKey, content] of Object.entries(itemTranslations)) {
+				const text = getContentPlainText(content).trim();
+				if (text) {
+					if (text.length > MAX_VISIBLE_TEXT_CHARS) visibleTextValueTruncated = true;
+					allVisibleText.push({
+						locale,
+						contentKey,
+						text: text.length > MAX_VISIBLE_TEXT_CHARS ? `${text.slice(0, MAX_VISIBLE_TEXT_CHARS)}...` : text
+					});
+				}
+			}
 		}
-	}
-	const roots = items.filter((item) => !parentById.has(item.id));
-	if (roots.length !== 1) add({
-		code: "root-count",
-		severity: "error",
-		category: "structure",
-		message: `Expected one survey root but found ${roots.length}.`
-	});
-	for (const parent of items) {
-		const siblingKeys = /* @__PURE__ */ new Map();
-		for (const childId of strings(isRecord(parent.config) ? parent.config.items : void 0)) {
-			const child = itemsById.get(childId);
-			if (!child) continue;
-			const existing = siblingKeys.get(child.key);
-			if (existing) add({
-				code: "duplicate-sibling-key",
-				severity: "error",
-				category: "structure",
-				itemId: child.id,
-				message: `Key "${child.key}" duplicates sibling "${existing}".`
-			});
-			siblingKeys.set(child.key, child.id);
+		return {
+			id: item.id,
+			key: item.key,
+			fullKey: fullKeyById.get(item.id) ?? item.key,
+			itemType: item.itemType,
+			itemLabel: getItemLabel(item),
+			visibleText: allVisibleText.slice(0, MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM),
+			visibleTextTruncated: allVisibleText.length > MAX_VISIBLE_TEXT_ENTRIES_PER_ITEM || visibleTextValueTruncated
+		};
+	};
+	const rootItemId = inspection.outline.find((item) => item.depth === 0)?.itemId;
+	const rootItem = rootItemId ? itemsById.get(rootItemId) : void 0;
+	const result = {
+		document: {
+			revision: snapshot.version.revision,
+			contentHash: snapshot.version.contentHash,
+			capabilityDigest: snapshot.version.capabilityDigest
+		},
+		survey: {
+			key: rootItem?.key,
+			locales: inspection.locales,
+			itemCount: inspection.itemCount,
+			selectedLocale: snapshot.ui.selectedLocale
+		}
+	};
+	const focusItem = options.focusItemId ? itemsById.get(options.focusItemId) : void 0;
+	if (focusItem) {
+		const parentId = parentById.get(focusItem.id);
+		const parentItem = parentId ? itemsById.get(parentId) : void 0;
+		const ancestorItems = [];
+		const seenAncestorIds = /* @__PURE__ */ new Set();
+		let ancestorId = parentId;
+		while (ancestorId && !seenAncestorIds.has(ancestorId)) {
+			seenAncestorIds.add(ancestorId);
+			const ancestor = itemsById.get(ancestorId);
+			if (!ancestor) break;
+			ancestorItems.unshift(ancestor);
+			ancestorId = parentById.get(ancestorId);
+		}
+		const siblingIds = parentItem ? childIdsByParent.get(parentItem.id) ?? [] : [];
+		const siblingItemCount = Math.max(0, siblingIds.length - 1);
+		const siblingItems = getCenteredNeighbors(siblingIds, siblingIds.indexOf(focusItem.id), MAX_SIBLING_ITEMS).map((itemId) => itemsById.get(itemId)).filter((item) => Boolean(item));
+		const allRelatedItems = [];
+		const seenRelatedIds = /* @__PURE__ */ new Set();
+		const pending = [...childIdsByParent.get(focusItem.id) ?? []];
+		while (pending.length > 0) {
+			const itemId = pending.shift();
+			const item = itemId ? itemsById.get(itemId) : void 0;
+			if (!item || seenRelatedIds.has(item.id)) continue;
+			seenRelatedIds.add(item.id);
+			allRelatedItems.push(item);
+			pending.push(...childIdsByParent.get(item.id) ?? []);
 		}
+		const relatedItems = allRelatedItems.slice(0, MAX_RELATED_ITEMS);
+		result.focus = {
+			item: summarizeItem(focusItem),
+			parent: parentItem ? summarizeItem(parentItem) : void 0,
+			ancestorPath: ancestorItems.map(summarizeItem),
+			siblingKeys: siblingItems.map((item) => item.key),
+			siblingItems: siblingItems.map(summarizeItem),
+			siblingItemCount,
+			siblingItemsTruncated: siblingItemCount > siblingItems.length,
+			relatedItems: relatedItems.map(summarizeItem),
+			relatedItemCount: allRelatedItems.length,
+			relatedItemsTruncated: allRelatedItems.length > relatedItems.length
+		};
 	}
-	const locales = context.inspection.locales;
-	const sourceLocale = options.sourceLocale ?? context.ui.selectedLocale ?? locales[0];
-	const targetLocales = options.targetLocales ?? locales.filter((locale) => locale !== sourceLocale);
-	const manifests = new Map(context.capabilities.itemTypes.map((entry) => [entry.itemType, entry]));
-	for (const item of items) {
-		const manifest = manifests.get(item.itemType);
-		if (!manifest) {
-			add({
-				code: "unsupported-item-type",
-				severity: "warning",
-				category: "structure",
-				itemId: item.id,
-				message: `Item type "${item.itemType}" is not advertised by the active editor.`
-			});
-			continue;
-		}
-		for (const surface of manifest.contentSurfaces.filter((entry) => entry.requiredOnCreate && !entry.pattern)) if (!translationText(context, sourceLocale, item.id, surface.key)) add({
-			code: "missing-primary-content",
-			severity: "warning",
-			category: "content",
-			itemId: item.id,
-			locale: sourceLocale,
-			contentKey: surface.key,
-			message: `Required respondent content "${surface.key}" is empty in ${sourceLocale}.`
+	if ((options.purpose === "suggest-item-key" || options.purpose === "suggest-item-label") && focusItem) {
+		const parentId = parentById.get(focusItem.id);
+		const siblingIds = parentId ? childIdsByParent.get(parentId) ?? [] : [];
+		const siblingPositionById = new Map(siblingIds.map((itemId, index) => [itemId, index]));
+		const focusSiblingPosition = siblingPositionById.get(focusItem.id);
+		const rankedItems = snapshot.survey.surveyItems.filter((item) => item.id !== focusItem.id).map((item, index) => ({
+			item,
+			index,
+			siblingDistance: focusSiblingPosition !== void 0 && siblingPositionById.has(item.id) ? Math.abs(siblingPositionById.get(item.id) - focusSiblingPosition) : Number.POSITIVE_INFINITY,
+			relationship: parentById.get(item.id) === parentId ? "sibling" : item.itemType === focusItem.itemType ? "same-type" : "survey"
+		})).sort((left, right) => {
+			const rank = {
+				sibling: 0,
+				"same-type": 1,
+				survey: 2
+			};
+			return rank[left.relationship] - rank[right.relationship] || left.siblingDistance - right.siblingDistance || left.index - right.index;
 		});
-		const sourceContent = isRecord(context.survey.translations?.[sourceLocale]?.itemTranslations?.[item.id]) ? context.survey.translations?.[sourceLocale]?.itemTranslations?.[item.id] : {};
-		for (const [contentKey, content] of Object.entries(sourceContent ?? {})) {
-			if (!getContentPlainText(content).trim()) continue;
-			for (const locale of targetLocales) if (!translationText(context, locale, item.id, contentKey)) add({
-				code: "missing-translation",
-				severity: "warning",
-				category: "localization",
-				itemId: item.id,
-				locale,
-				contentKey,
-				message: `Content "${contentKey}" has source text but no ${locale} translation.`
-			});
-		}
-		const config = isRecord(item.config) ? item.config : {};
-		if (item.itemType === "choiceItem") {
-			const optionsList = records(config.options);
-			if (optionsList.length === 0) add({
-				code: "choice-without-options",
-				severity: "error",
-				category: "content",
+		const allKeyExamples = rankedItems.map(({ item, relationship }) => ({
+			itemId: item.id,
+			itemType: item.itemType,
+			key: item.key,
+			relationship
+		}));
+		const allLabelExamples = rankedItems.flatMap(({ item, relationship }) => {
+			const label = getItemLabel(item);
+			return label ? [{
 				itemId: item.id,
-				message: "Choice item has no options."
-			});
-			for (const option of optionsList) {
-				if (typeof option.id === "string" && !translationText(context, sourceLocale, item.id, `options.${option.id}.label`)) add({
-					code: "missing-option-label",
-					severity: "warning",
-					category: "content",
+				itemType: item.itemType,
+				key: item.key,
+				label,
+				relationship
+			}] : [];
+		});
+		result.naming = {
+			keyExamples: allKeyExamples.slice(0, MAX_NAMING_EXAMPLES),
+			keyExampleCount: allKeyExamples.length,
+			keyExamplesTruncated: allKeyExamples.length > MAX_NAMING_EXAMPLES,
+			labelExamples: allLabelExamples.slice(0, MAX_NAMING_EXAMPLES),
+			labelExampleCount: allLabelExamples.length,
+			labelExamplesTruncated: allLabelExamples.length > MAX_NAMING_EXAMPLES
+		};
+	}
+	const sourceLocale = options.sourceLocale;
+	if (options.purpose === "translate-content" && sourceLocale) {
+		const relevantLocales = [sourceLocale, ...options.targetLocales ?? []];
+		const sourceTokens = new Set((options.sourceTexts ?? []).flatMap((text) => text.toLocaleLowerCase().split(/[^\p{L}\p{N}]+/u)).filter((token) => token.length >= 3));
+		const allExamples = [];
+		snapshot.survey.surveyItems.forEach((item, itemIndex) => {
+			const contentKeys = /* @__PURE__ */ new Set();
+			for (const locale of relevantLocales) {
+				const itemTranslations = snapshot.survey.translations?.[locale]?.itemTranslations?.[item.id];
+				for (const contentKey of Object.keys(itemTranslations ?? {})) contentKeys.add(contentKey);
+			}
+			for (const contentKey of contentKeys) {
+				const values = {};
+				for (const locale of relevantLocales) {
+					const content = snapshot.survey.translations?.[locale]?.itemTranslations?.[item.id]?.[contentKey];
+					if (!content) continue;
+					const text = getContentPlainText(content).trim();
+					if (text) values[locale] = text.slice(0, MAX_VISIBLE_TEXT_CHARS);
+				}
+				const sourceText = values[sourceLocale];
+				if (!sourceText || Object.keys(values).length < 2) continue;
+				const normalizedSource = sourceText.toLocaleLowerCase();
+				const score = [...sourceTokens].reduce((total, token) => total + (normalizedSource.includes(token) ? 1 : 0), 0);
+				allExamples.push({
 					itemId: item.id,
-					locale: sourceLocale,
-					contentKey: `options.${option.id}.label`,
-					message: `Choice option "${option.id}" has no visible label.`
+					contentKey,
+					values,
+					score,
+					order: itemIndex
 				});
-				if (typeof option.id === "string" && option.embeddedForm) {
-					for (const group of getGroups(item, option.id)) for (const field of records(group.fields)) if (typeof field.id === "string" && !translationText(context, sourceLocale, item.id, `embeddedForms.${option.id}.fields.${field.id}.label`)) add({
-						code: "missing-field-label",
-						severity: "warning",
-						category: "content",
-						itemId: item.id,
-						locale: sourceLocale,
-						contentKey: `embeddedForms.${option.id}.fields.${field.id}.label`,
-						message: `Embedded field "${field.id}" has no visible label.`
-					});
-				}
 			}
+		});
+		allExamples.sort((left, right) => right.score - left.score || left.order - right.order);
+		result.translation = {
+			examples: allExamples.slice(0, MAX_TRANSLATION_EXAMPLES).map(({ itemId, contentKey, values }) => ({
+				itemId,
+				contentKey,
+				values
+			})),
+			exampleCount: allExamples.length,
+			examplesTruncated: allExamples.length > MAX_TRANSLATION_EXAMPLES
+		};
+	}
+	return result;
+};
+//#endregion
+//#region src/engine/task-result-cache.ts
+const DEFAULT_TTL_MS = 900 * 1e3;
+const DEFAULT_MAX_ENTRIES = 64;
+/** Small in-memory LRU cache for deterministic, snapshot-scoped one-shot results. */
+var SurveyAssistantTaskResultCache = class {
+	entries = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	now;
+	constructor(options = {}) {
+		this.ttlMs = Math.max(0, options.ttlMs ?? DEFAULT_TTL_MS);
+		this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+		this.now = options.now ?? Date.now;
+	}
+	get(key) {
+		const entry = this.entries.get(key);
+		if (!entry) return void 0;
+		if (entry.expiresAt <= this.now()) {
+			this.entries.delete(key);
+			return;
 		}
-		if (item.itemType === "formItem") {
-			const groups = getGroups(item);
-			if (groups.length === 0) add({
-				code: "form-without-groups",
-				severity: "error",
-				category: "content",
-				itemId: item.id,
-				message: "Form item has no field groups."
-			});
-			for (const group of groups) for (const field of records(group.fields)) if (typeof field.id === "string" && !translationText(context, sourceLocale, item.id, `fields.${field.id}.label`)) add({
-				code: "missing-field-label",
-				severity: "warning",
-				category: "content",
-				itemId: item.id,
-				locale: sourceLocale,
-				contentKey: `fields.${field.id}.label`,
-				message: `Form field "${field.id}" has no visible label.`
-			});
-		}
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+		return entry.value;
 	}
-	const assets = context.survey.assets ?? {};
-	for (const [assetId, asset] of Object.entries(assets)) {
-		const metadata = isRecord(asset.metadata) ? asset.metadata : {};
-		if (asset.kind === "image" && typeof metadata.alt !== "string") add({
-			code: "missing-image-alt",
-			severity: "warning",
-			category: "assets",
-			message: `Image asset "${assetId}" has no alternative text.`,
-			suggestion: "Add concise alt text, or an empty alt value when the image is purely decorative."
+	set(key, value) {
+		this.entries.delete(key);
+		this.entries.set(key, {
+			expiresAt: this.now() + this.ttlMs,
+			value
 		});
+		while (this.entries.size > this.maxEntries) {
+			const oldestKey = this.entries.keys().next().value;
+			if (oldestKey === void 0) break;
+			this.entries.delete(oldestKey);
+		}
+	}
+	clear() {
+		this.entries.clear();
 	}
-	const limited = findings.slice(0, options.maxFindings ?? 200);
-	return {
-		summary: limited.reduce((acc, entry) => {
-			acc[entry.severity] += 1;
-			acc.total += 1;
-			return acc;
-		}, {
-			error: 0,
-			warning: 0,
-			info: 0,
-			total: 0
-		}),
-		metrics: {
-			itemCount: context.inspection.itemCount,
-			localeCount: locales.length,
-			responseSlotCount: context.inspection.responseSlots.length,
-			assetCount: Object.keys(assets).length,
-			itemTypes
-		},
-		findings: limited,
-		qualityReviewPrinciples: QUALITY_PRINCIPLES,
-		note: "Technical findings are deterministic. Quality principles are a structured review rubric; apply them with human/model judgment and domain context, and do not present them as psychometric validation."
-	};
 };
 //#endregion
-export { deriveResponseSlotTypes as $, getRawSurvey$1 as A, resolveItemSummary as B, clampLimit as C, formFieldGroupLayoutSchema as D, formFieldGroupDetailsSchema as E, mapKeyIndexById as F, summarizeKeyIndexEntry as G, summarizeFocusItemNode as H, mapOutlineById as I, translationEntrySchema as J, summarizeOutlineNode as K, mapRawItemsById as L, itemConfigDetailsSchema as M, itemMatchesQuery as N, formSelectOptionDetailsSchema as O, itemSummarySchema as P, createSurveyAssistantEngineContext as Q, normalizeText as R, choiceOptionDetailsSchema as S, formFieldDetailsSchema as T, summarizeItemById as U, sliceWithCursor as V, summarizeKeyIndexEntries as W, inferExpressionReturnType as X, unique as Y, validateExpression as Z, buildConfigSearchText as _, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_PROPOSAL as a, buildItemTranslationEntries as b, buildSurveyDocumentVersion as c, normalizeSurveyChangeOperations as d, buildExpressionMutationPatches as f, MAX_LIMIT as g, DEFAULT_LIMIT as h, TurnSurveyDraft as i, getRawSurveyItems as j, getKeyIndexEntries as k, createSurveyChangeSet as l, expressionSchema as m, SurveyAssistantTaskResultCache as n, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT as o, expressionMutationSchema as p, summarizeRawItem as q, buildSurveyAssistantTaskContext as r, applyValidatedSurveyOperationsToDraft as s, auditSurvey as t, validateSurveyOperations as u, buildEmbeddedFormDetails as v, findDirectChildrenByFullKey as w, buildSurveyTranslations as x, buildItemConfigDetails as y, parseCursor as z };
+export { deriveResponseSlotTypes as $, getRawSurvey$1 as A, resolveItemSummary as B, clampLimit as C, formFieldGroupLayoutSchema as D, formFieldGroupDetailsSchema as E, mapKeyIndexById as F, summarizeKeyIndexEntry as G, summarizeFocusItemNode as H, mapOutlineById as I, translationEntrySchema as J, summarizeOutlineNode as K, mapRawItemsById as L, itemConfigDetailsSchema as M, itemMatchesQuery as N, formSelectOptionDetailsSchema as O, itemSummarySchema as P, createSurveyAssistantEngineContext as Q, normalizeText as R, choiceOptionDetailsSchema as S, formFieldDetailsSchema as T, summarizeItemById as U, sliceWithCursor as V, summarizeKeyIndexEntries as W, inferExpressionReturnType as X, unique as Y, validateExpression as Z, buildConfigSearchText as _, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_PROPOSAL as a, buildItemTranslationEntries as b, buildSurveyDocumentVersion as c, normalizeSurveyChangeOperations as d, buildExpressionMutationPatches as f, MAX_LIMIT as g, DEFAULT_LIMIT as h, auditSurvey as i, getRawSurveyItems as j, getKeyIndexEntries as k, createSurveyChangeSet as l, expressionSchema as m, buildSurveyAssistantTaskContext as n, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT as o, expressionMutationSchema as p, summarizeRawItem as q, TurnSurveyDraft as r, applyValidatedSurveyOperationsToDraft as s, SurveyAssistantTaskResultCache as t, validateSurveyOperations as u, buildEmbeddedFormDetails as v, findDirectChildrenByFullKey as w, buildSurveyTranslations as x, buildItemConfigDetails as y, parseCursor as z };
 
-//# sourceMappingURL=engine-0AJrv0hI.mjs.map
+//# sourceMappingURL=engine-CWTuN3o2.mjs.map