@case-framework/survey-assistant 0.4.0 → 0.6.0

package/dist/{engine-BvfUx_Jx.mjs → engine-CQwOAcwK.mjs}

@@ -1,5 +1,5 @@
 import { I as rawSurveyDocumentSchema, f as surveyChangeSetSchema, l as surveyAssistantTurnFinalSchema } from "./protocol-DJUP4gc0.mjs";
-import { a as normalizeFormAuthoringConfig, c as assertSurveyAssistantCapabilities, i as isValidSimpleFormConfig, o as transitionFormAuthoringMode, r as isCompatibleSimpleFieldUpsert, t as getFormAuthoringMode } from "./form-authoring-BQh40yDb.mjs";
+import { a as normalizeFormAuthoringConfig, c as assertSurveyAssistantCapabilities, i as isValidSimpleFormConfig, o as transitionFormAuthoringMode, r as isCompatibleSimpleFieldUpsert, t as getFormAuthoringMode } from "./form-authoring-kQDgC5oz.mjs";
 import { z } from "zod";
 import { ContentType, Expression, ExpressionType, FunctionExpressionNames, JsonPatchError, ReservedSurveyItemTypes, SurveyItemTranslations, SurveyTranslations, ValueReference, ValueReferenceMethod, ValueType, analyzeSurveyExpressionReferences, applyJsonPatch, findIntroducedExpressionReferenceDiagnostics, generateId, getContentPlainText, isContentEmpty, parseJsonPointer, structuredCloneMethod } from "@case-framework/survey-core";
 //#region src/engine/context.ts
@@ -2398,10 +2398,20 @@ const validateSurveyTreeStructure = (survey, operationId, availableItemTypes) =>
 	for (const item of itemsById.values()) {
 		const childRefs = (isRecord$2(item.config) ? item.config : void 0)?.items;
 		if (childRefs === void 0) continue;
-		if (item.itemType !== ReservedSurveyItemTypes.Group || !Array.isArray(childRefs)) {
+		if (!Array.isArray(childRefs)) {
 			issues.push(createStructureIssue({
 				code: "invalid-group-items",
-				message: `Item "${item.id}" has an items array but is not a valid group item.`,
+				message: `Item "${item.id}" has an invalid group items value.`,
+				operationId,
+				itemId: item.id
+			}));
+			continue;
+		}
+		if (item.itemType !== ReservedSurveyItemTypes.Group) {
+			if (childRefs.length === 0) continue;
+			issues.push(createStructureIssue({
+				code: "invalid-group-items",
+				message: `Item "${item.id}" has child references but is not a valid group item.`,
 				operationId,
 				itemId: item.id
 			}));
@@ -2510,7 +2520,7 @@ const collectIntroducedExpressionIntegrityIssues = ({ after, before, operationId
 	operationId,
 	itemId: diagnostic.ownerItemId
 }));
-const validateSurveyJsonPatchOperation = ({ operation, snapshot }) => {
+const validateSurveyJsonPatchOperation = ({ allowExpressionJsonPatches, operation, snapshot }) => {
 	const operationId = getOperationId(operation);
 	const issues = [];
 	const warnings = [];
@@ -2525,6 +2535,19 @@ const validateSurveyJsonPatchOperation = ({ operation, snapshot }) => {
 			operationIndex: 0,
 			operationId
 		}));
+		const segments = parseJsonPointer(path);
+		const expressionOwnedPath = segments[0] === "templateValues" || segments[0] === "surveyItems" && [
+			"displayConditions",
+			"disabledConditions",
+			"validations",
+			"prefills"
+		].includes(segments[2] ?? "");
+		if (!allowExpressionJsonPatches && expressionOwnedPath) issues.push(createIssue({
+			code: "expression-patch-requires-specialized-tool",
+			message: "Use survey_expression for display conditions, disabled conditions, expression validations, prefills, and template values. A raw survey patch cannot modify an expression-owned location.",
+			operationIndex: 0,
+			operationId
+		}));
 	} catch (error) {
 		issues.push(createIssue({
 			code: "invalid-json-pointer",
@@ -3456,7 +3479,7 @@ const getDeletedAncestor = (itemId, parentByChildId, deletedItemIds) => {
 };
 const buildSurveyDocumentVersion = (snapshot) => ({ ...snapshot.version });
 const resolveEngineContext = (snapshot) => "document" in snapshot ? snapshot : createSurveyAssistantEngineContext(snapshot);
-const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: snapshotInput }) => {
+const validateSurveyOperations = ({ allowExpressionJsonPatches = false, maxOperations = 200, operations, snapshot: snapshotInput }) => {
 	if (!snapshotInput) return createEmptyValidationResult(createIssue({
 		code: "missing-snapshot",
 		message: "No live editor snapshot was provided for this assistant turn."
@@ -3479,6 +3502,7 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 			operationId: surveyJsonPatchOperations[0]?.id
 		}), operations);
 		return validateSurveyJsonPatchOperation({
+			allowExpressionJsonPatches,
 			operation: surveyJsonPatchOperations[0],
 			snapshot
 		});
@@ -4675,7 +4699,7 @@ const validateSurveyOperations = ({ maxOperations = 200, operations, snapshot: s
 		}
 	});
 	if (issues.length === 0) try {
-		const prospectiveSurvey = applyValidatedSurveyOperationsToDraft({
+		const prospectiveSurvey = executeSurveyOperationsOnRawSurvey({
 			operations: normalizedOperations,
 			survey: snapshot.survey
 		});
@@ -4719,11 +4743,12 @@ const removeDraftTranslationPrefix = ({ itemId, prefix, survey }) => {
 	survey.translations = surveyTranslations.serialize();
 };
 /**
-* Applies already-normalized, validated operations to a request-local raw
-* survey. This is simulation only; the editor remains the final mutation and
-* undo/redo owner.
+* Canonical pure executor for already-normalized, validated survey operation
+* semantics. Raw-draft simulation uses the returned survey directly; editor
+* adapters use it to decide domain results before recording them through the
+* editor's normal mutation and history APIs.
 */
-const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey }) => {
+const executeSurveyOperationsOnRawSurvey = ({ operations, survey: inputSurvey }) => {
 	let survey = structuredCloneMethod(inputSurvey);
 	const getItem = (itemId) => {
 		const item = survey.surveyItems.find((candidate) => candidate.id === itemId);
@@ -4957,12 +4982,21 @@ const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey
 						translations: operation.translations
 					});
 				} else if (operation.kind === "remove-form-field-group") {
+					const removedGroup = groups.find((group) => group.id === operation.groupId);
 					groups = groups.filter((group) => group.id !== operation.groupId);
 					removeDraftTranslationPrefix({
 						itemId: item.id,
 						prefix: `${operation.target.optionId ? `embeddedForms.${operation.target.optionId}.` : ""}fieldGroups.${operation.groupId}`,
 						survey
 					});
+					for (const field of removedGroup?.fields ?? []) {
+						if (typeof field.id !== "string") continue;
+						removeDraftTranslationPrefix({
+							itemId: item.id,
+							prefix: `${operation.target.optionId ? `embeddedForms.${operation.target.optionId}.` : ""}fields.${field.id}`,
+							survey
+						});
+					}
 				} else if (operation.kind === "reorder-form-field-groups") {
 					const byId = new Map(groups.map((group) => [group.id, group]));
 					groups = operation.groupIds.map((groupId) => byId.get(groupId));
@@ -5008,13 +5042,17 @@ const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey
 			case "remove-item": {
 				const removeIds = collectDescendantIds(operation.itemId, new Map(survey.surveyItems.map((item) => [item.id, item])));
 				removeIds.add(operation.itemId);
-				survey.surveyItems = survey.surveyItems.filter((item) => !removeIds.has(item.id)).map((item) => ({
-					...item,
-					config: isRecord$2(item.config) ? {
-						...item.config,
-						items: getGroupChildren(item).filter((id) => !removeIds.has(id))
-					} : item.config
-				}));
+				survey.surveyItems = survey.surveyItems.filter((item) => !removeIds.has(item.id)).map((item) => {
+					if (!isRecord$2(item.config) || !Array.isArray(item.config.items)) return item;
+					const items = item.config.items.filter((itemId) => typeof itemId === "string" && !removeIds.has(itemId));
+					return items.length === item.config.items.length ? item : {
+						...item,
+						config: {
+							...item.config,
+							items
+						}
+					};
+				});
 				const translations = new SurveyTranslations(survey.translations);
 				for (const itemId of removeIds) translations.setItemTranslations(itemId, void 0);
 				survey.translations = translations.serialize();
@@ -5121,8 +5159,11 @@ const applyValidatedSurveyOperationsToDraft = ({ operations, survey: inputSurvey
 	}
 	return rawSurveyDocumentSchema.parse(survey);
 };
-const createSurveyChangeSet = ({ maxOperations, operations, snapshot, summary, turnId }) => {
+/** @deprecated Prefer `executeSurveyOperationsOnRawSurvey` for new integrations. */
+const applyValidatedSurveyOperationsToDraft = executeSurveyOperationsOnRawSurvey;
+const createSurveyChangeSet = ({ allowExpressionJsonPatches, maxOperations, operations, snapshot, summary, turnId }) => {
 	const validation = validateSurveyOperations({
+		allowExpressionJsonPatches,
 		maxOperations,
 		operations,
 		snapshot
@@ -5170,6 +5211,11 @@ const QUALITY_PRINCIPLES = [
 		title: "Response option quality",
 		prompt: "Are options mutually exclusive, collectively sufficient, balanced, ordered, and consistently scaled?"
 	},
+	{
+		id: "key-semantic-consistency",
+		title: "Coding-key consistency",
+		prompt: "Do item, option, and field keys follow the survey's established convention and avoid contradicting the content they currently identify? Generic, numeric, or opaque keys are acceptable when that is the survey's consistent pattern; flag descriptive keys when they have become stale or misleading, and mixed conventions when the inconsistency appears accidental."
+	},
 	{
 		id: "flow",
 		title: "Flow and completeness",
@@ -5207,6 +5253,75 @@ const translationText = (context, locale, itemId, contentKey) => {
 	const content = (isRecord$1(itemTranslations?.[itemId]) ? itemTranslations[itemId] : void 0)?.[contentKey];
 	return content ? getContentPlainText(content).trim() : "";
 };
+const summarizeItemContent = (context, locale, item) => {
+	if (!locale) return {};
+	const itemContent = context.survey.translations?.[locale]?.itemTranslations?.[item.id];
+	if (!isRecord$1(itemContent)) return {};
+	for (const contentKey of [
+		"title",
+		"content",
+		"subtitle",
+		"topContent",
+		"bottomContent"
+	]) {
+		const content = itemContent[contentKey];
+		if (!content) continue;
+		const text = getContentPlainText(content).trim();
+		if (text) return {
+			contentKey,
+			content: text
+		};
+	}
+	return {};
+};
+const collectKeyReviewEntries = (context, sourceLocale) => {
+	const entries = [];
+	const addFormFields = (item, groups, contentPrefix) => {
+		for (const group of groups) for (const field of records(group.fields)) {
+			if (typeof field.id !== "string" || typeof field.key !== "string") continue;
+			const contentKey = `${contentPrefix}fields.${field.id}.label`;
+			const content = sourceLocale ? translationText(context, sourceLocale, item.id, contentKey) : "";
+			entries.push({
+				kind: "form-field",
+				itemId: item.id,
+				itemKey: item.key,
+				key: field.key,
+				keySource: "explicit",
+				contentKey,
+				...content ? { content } : {}
+			});
+		}
+	};
+	for (const item of context.survey.surveyItems) {
+		entries.push({
+			kind: "item",
+			itemId: item.id,
+			itemKey: item.key,
+			key: item.key,
+			keySource: "explicit",
+			...summarizeItemContent(context, sourceLocale, item)
+		});
+		const config = isRecord$1(item.config) ? item.config : {};
+		if (item.itemType === "choiceItem") for (const option of records(config.options)) {
+			if (typeof option.id !== "string") continue;
+			const explicitKey = typeof option.key === "string" && option.key.trim() ? option.key : null;
+			const contentKey = `options.${option.id}.label`;
+			const content = sourceLocale ? translationText(context, sourceLocale, item.id, contentKey) : "";
+			entries.push({
+				kind: "choice-option",
+				itemId: item.id,
+				itemKey: item.key,
+				key: explicitKey ?? option.id,
+				keySource: explicitKey ? "explicit" : "fallback-id",
+				contentKey,
+				...content ? { content } : {}
+			});
+			if (option.embeddedForm) addFormFields(item, getGroups(item, option.id), `embeddedForms.${option.id}.`);
+		}
+		else if (item.itemType === "formItem") addFormFields(item, getGroups(item), "");
+	}
+	return entries;
+};
 const getGroups = (item, optionId) => {
 	const config = isRecord$1(item.config) ? item.config : {};
 	if (!optionId) return records(config.fieldGroups);
@@ -5285,6 +5400,10 @@ const auditSurvey = (context, options = {}) => {
 	const locales = context.inspection.locales;
 	const sourceLocale = options.sourceLocale ?? context.ui.selectedLocale ?? locales[0];
 	const targetLocales = options.targetLocales ?? locales.filter((locale) => locale !== sourceLocale);
+	const allKeyReviewEntries = collectKeyReviewEntries(context, sourceLocale);
+	const keyReviewOffset = Math.min(options.keyReviewOffset ?? 0, allKeyReviewEntries.length);
+	const keyReviewLimit = options.keyReviewLimit ?? 30;
+	const keyReviewEntries = allKeyReviewEntries.slice(keyReviewOffset, keyReviewOffset + keyReviewLimit);
 	const manifests = new Map(context.capabilities.itemTypes.map((entry) => [entry.itemType, entry]));
 	for (const item of items) {
 		const manifest = manifests.get(item.itemType);
@@ -5416,6 +5535,15 @@ const auditSurvey = (context, options = {}) => {
 		},
 		findings: limited,
 		qualityReviewPrinciples: QUALITY_PRINCIPLES,
+		keyReview: {
+			sourceLocale,
+			entryCount: allKeyReviewEntries.length,
+			offset: keyReviewOffset,
+			returnedEntryCount: keyReviewEntries.length,
+			truncated: keyReviewOffset + keyReviewEntries.length < allKeyReviewEntries.length,
+			entries: keyReviewEntries,
+			note: "These key/content pairs are evidence for qualitative review, not deterministic defects. Judge them against the survey's own naming pattern; generic or opaque keys are not inherently problematic."
+		},
 		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."
 	};
 };
@@ -5458,6 +5586,16 @@ const operationTargets = (operation) => {
 	}
 };
 const collectOperationTargets = (operations) => new Set(operations.flatMap(operationTargets));
+const mutationRecoveryRouteByIssueCode = { "expression-patch-requires-specialized-tool": "expression" };
+const mutationRouteTarget = (route) => `mutation-route:${route}`;
+const collectExclusiveMutationRecoveryTargets = (changeSet) => {
+	const errorIssues = changeSet.validation.issues.filter((issue) => issue.severity === "error");
+	if (errorIssues.length === 0) return void 0;
+	const routes = errorIssues.map((issue) => mutationRecoveryRouteByIssueCode[issue.code]);
+	const knownRoutes = routes.filter((route) => route !== void 0);
+	if (knownRoutes.length !== routes.length) return void 0;
+	return new Set(knownRoutes.map(mutationRouteTarget));
+};
 const MAX_POST_CHANGE_TARGETS = 16;
 const MAX_POST_CHANGE_ITEMS = 6;
 const MAX_POST_CHANGE_TRANSLATIONS = 12;
@@ -5584,18 +5722,23 @@ var TurnSurveyDraft = class {
 		if (this.#context) throw new Error("The survey turn draft was initialized more than once.");
 		this.#context = context;
 	}
-	stage({ addressedTargets = [], operations, snapshot, summary }) {
+	stage({ addressedTargets = [], allowExpressionJsonPatches = false, handledMutationRoutes = [], 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 targets = new Set([
+			...collectOperationTargets(operations),
+			...addressedTargets,
+			...handledMutationRoutes.map(mutationRouteTarget)
+		]);
 		const delta = createSurveyChangeSet({
+			allowExpressionJsonPatches,
 			operations,
 			snapshot: currentContext,
 			summary,
 			turnId: this.turnId
 		});
-		if (delta.status !== "validated" || !delta.validation.valid) return this.reject(delta, targets);
+		if (delta.status !== "validated" || !delta.validation.valid) return this.reject(delta, collectExclusiveMutationRecoveryTargets(delta) ?? targets);
 		const cumulativeOperations = [...this.#draftOperations, ...delta.operations];
 		if (cumulativeOperations.length > 1e3) return this.reject(createSurveyChangeSet({
 			maxOperations: MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT,
@@ -5606,7 +5749,7 @@ var TurnSurveyDraft = class {
 		}), targets);
 		const beforeContext = this.#context;
 		if (this.#context) {
-			const survey = applyValidatedSurveyOperationsToDraft({
+			const survey = executeSurveyOperationsOnRawSurvey({
 				operations: delta.operations,
 				survey: this.#context.survey
 			});
@@ -5937,6 +6080,6 @@ var SurveyAssistantTaskResultCache = class {
 	}
 };
 //#endregion
-export { validateExpression 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, inferExpressionReturnType as Q, normalizeText as R, choiceOptionDetailsSchema as S, formFieldDetailsSchema as T, summarizeItemById as U, sliceWithCursor as V, summarizeKeyIndexEntries as W, analyzeSurveyAssistantExpressionReferences as X, unique as Y, deriveSurveyExpressionResponseSlots as Z, buildConfigSearchText as _, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_PROPOSAL as a, buildItemTranslationEntries as b, buildSurveyDocumentVersion as c, normalizeSurveyChangeOperations as d, createSurveyAssistantEngineContext as et, 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, deriveResponseSlotTypes as tt, validateSurveyOperations as u, buildEmbeddedFormDetails as v, findDirectChildrenByFullKey as w, buildSurveyTranslations as x, buildItemConfigDetails as y, parseCursor as z };
+export { inferExpressionReturnType as $, getKeyIndexEntries as A, parseCursor as B, choiceOptionDetailsSchema as C, formFieldGroupDetailsSchema as D, formFieldDetailsSchema as E, itemSummarySchema as F, summarizeKeyIndexEntries as G, sliceWithCursor as H, mapKeyIndexById as I, summarizeRawItem as J, summarizeKeyIndexEntry as K, mapOutlineById as L, getRawSurveyItems as M, itemConfigDetailsSchema as N, formFieldGroupLayoutSchema as O, itemMatchesQuery as P, deriveSurveyExpressionResponseSlots as Q, mapRawItemsById as R, buildSurveyTranslations as S, findDirectChildrenByFullKey as T, summarizeFocusItemNode as U, resolveItemSummary as V, summarizeItemById as W, unique as X, translationEntrySchema as Y, analyzeSurveyAssistantExpressionReferences as Z, MAX_LIMIT as _, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_PROPOSAL as a, buildItemConfigDetails as b, buildSurveyDocumentVersion as c, validateSurveyOperations as d, validateExpression as et, normalizeSurveyChangeOperations as f, DEFAULT_LIMIT as g, expressionSchema as h, auditSurvey as i, getRawSurvey$1 as j, formSelectOptionDetailsSchema as k, createSurveyChangeSet as l, expressionMutationSchema as m, buildSurveyAssistantTaskContext as n, deriveResponseSlotTypes as nt, MAX_SURVEY_ASSISTANT_OPERATIONS_PER_TURN_DRAFT as o, buildExpressionMutationPatches as p, summarizeOutlineNode as q, TurnSurveyDraft as r, applyValidatedSurveyOperationsToDraft as s, SurveyAssistantTaskResultCache as t, createSurveyAssistantEngineContext as tt, executeSurveyOperationsOnRawSurvey as u, buildConfigSearchText as v, clampLimit as w, buildItemTranslationEntries as x, buildEmbeddedFormDetails as y, normalizeText as z };
 
-//# sourceMappingURL=engine-BvfUx_Jx.mjs.map
+//# sourceMappingURL=engine-CQwOAcwK.mjs.map