@case-framework/survey-assistant 0.1.0 → 0.2.0

package/dist/{tools-Hz2p7vyv.mjs → tools-DDXaJ8Za.mjs}

@@ -1,12 +1,92 @@
-import { W as assistantItemTypeManifestSchema, gt as surveyOperationSchema, u as surveyChangeSetSchema } from "./protocol-DV0ka9WT.mjs";
-import { a as getDeterministicCreateItemTypes, o as inspectAssistantItem, s as resolveAssistantCapabilityReference } from "./capabilities-B6tvE7fK.mjs";
-import { A as getRawSurvey, B as resolveItemSummary, C as clampLimit, F as mapKeyIndexById, H as summarizeFocusItemNode, I as mapOutlineById, J as translationEntrySchema, K as summarizeOutlineNode, L as mapRawItemsById, M as itemConfigDetailsSchema, N as itemMatchesQuery, P as itemSummarySchema, R as normalizeText, U as summarizeItemById, V as sliceWithCursor, W as summarizeKeyIndexEntries, Y as unique, _ as buildConfigSearchText, a as SURVEY_CHANGE_CONTINUATION_MODES, b as buildItemTranslationEntries, d as normalizeSurveyChangeOperations, f as buildExpressionMutationPatches, i as SURVEY_CHANGE_CONTINUATION_DESCRIPTION, j as getRawSurveyItems, k as getKeyIndexEntries, l as createSurveyChangeSet, p as expressionMutationSchema, q as summarizeRawItem, t as auditSurvey, v as buildEmbeddedFormDetails, w as findDirectChildrenByFullKey, y as buildItemConfigDetails } from "./engine-sPvuixWg.mjs";
-import { r as requireSurveyAssistantTurnState } from "./request-context-jcmXT_Q2.mjs";
-import { n as surveyAuthoringReferences, t as surveyAuthoringReferenceTopics } from "./authoring-references-X6uRaWuf.mjs";
+import { G as assistantItemTypeManifestSchema, J as SURVEY_OPERATION_KINDS, _t as surveyOperationSchema, u as surveyChangeSetSchema, vt as surveyOperationSchemasByKind } from "./protocol-7EEgcYja.mjs";
+import { a as getDeterministicCreateItemTypes, o as inspectAssistantItem, s as resolveAssistantCapabilityReference } from "./capabilities-DZ0a_o2y.mjs";
+import { A as getRawSurvey, B as resolveItemSummary, C as clampLimit, F as mapKeyIndexById, H as summarizeFocusItemNode, I as mapOutlineById, J as translationEntrySchema, K as summarizeOutlineNode, L as mapRawItemsById, M as itemConfigDetailsSchema, N as itemMatchesQuery, P as itemSummarySchema, R as normalizeText, U as summarizeItemById, V as sliceWithCursor, W as summarizeKeyIndexEntries, Y as unique, _ as buildConfigSearchText, a as SURVEY_CHANGE_CONTINUATION_MODES, b as buildItemTranslationEntries, d as normalizeSurveyChangeOperations, f as buildExpressionMutationPatches, i as SURVEY_CHANGE_CONTINUATION_DESCRIPTION, j as getRawSurveyItems, k as getKeyIndexEntries, l as createSurveyChangeSet, p as expressionMutationSchema, q as summarizeRawItem, t as auditSurvey, v as buildEmbeddedFormDetails, w as findDirectChildrenByFullKey, y as buildItemConfigDetails } from "./engine-DQrCO_ur.mjs";
+import { a as requireSurveyAssistantTurnState } from "./request-context-BDBw4-Gw.mjs";
+import { n as surveyAuthoringReferenceTopics, r as surveyAuthoringReferences, t as getBuiltInItemTypeAuthoringReference } from "./authoring-references-DYuOAdVx.mjs";
 import { z } from "zod";
-import { JsonPatchError, encodeJsonPointerSegment, getAssetUsagesFromContent, getValueAtJsonPointer } from "@case-framework/survey-core";
+import { JsonPatchError, SURVEY_EDITOR_ITEM_COLORS, encodeJsonPointerSegment, getAssetUsagesFromContent, getValueAtJsonPointer } from "@case-framework/survey-core";
 import { randomUUID } from "node:crypto";
 import { createTool, isValidationError } from "@mastra/core/tools";
+//#region src/server/operation-contract-reference.ts
+const isSurveyOperationKind = (value) => SURVEY_OPERATION_KINDS.includes(value);
+const SURVEY_OPERATION_CONTRACT_DETAIL_LEVELS = ["compact", "full"];
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const summarizeLargeSchema = (schema, propertyName) => {
+	const description = typeof schema.description === "string" ? schema.description : propertyName ? `Canonical value for "${propertyName}".` : "Canonical value.";
+	const type = typeof schema.type === "string" ? schema.type : void 0;
+	return {
+		...type ? { type } : {},
+		description: `${description} The deeply nested schema is omitted from this compact reference; load the dedicated authoring reference when this structured value is needed.`
+	};
+};
+const compactJsonSchema = (value, propertyName, depth = 0) => {
+	if (Array.isArray(value)) return value.map((entry) => compactJsonSchema(entry, propertyName, depth + 1));
+	if (!isRecord$1(value)) return value;
+	if (typeof value.$ref === "string") return { description: "Recursive structured value omitted from this compact reference; request full detail only for protocol debugging." };
+	if (depth >= 3 && JSON.stringify(value).length > 12e3) return summarizeLargeSchema(value, propertyName);
+	const compact = {};
+	for (const key of [
+		"type",
+		"const",
+		"enum",
+		"description",
+		"minimum",
+		"maximum",
+		"minLength",
+		"maxLength",
+		"minItems",
+		"maxItems",
+		"required",
+		"additionalProperties"
+	]) if (value[key] !== void 0) compact[key] = value[key];
+	if (isRecord$1(value.properties)) compact.properties = Object.fromEntries(Object.entries(value.properties).map(([key, schema]) => [key, compactJsonSchema(schema, key, depth + 1)]));
+	if (value.items !== void 0) compact.items = compactJsonSchema(value.items, propertyName, depth + 1);
+	for (const unionKey of ["oneOf", "anyOf"]) if (Array.isArray(value[unionKey])) compact[unionKey] = value[unionKey].map((entry) => compactJsonSchema(entry, propertyName, depth + 1));
+	return compact;
+};
+const formatItemCapabilityProfile = (manifest, kind) => {
+	const fixedSurfaces = manifest.contentSurfaces.filter((surface) => !surface.pattern);
+	const patternedSurfaces = manifest.contentSurfaces.filter((surface) => surface.pattern);
+	const requiredSurfaces = fixedSurfaces.filter((surface) => surface.requiredOnCreate);
+	const lines = [
+		`## Item capability: \`${manifest.itemType}\``,
+		"",
+		`${manifest.displayName}: ${manifest.description ?? "No additional description."}`,
+		`Creation mode: ${manifest.create}.`,
+		manifest.authoring?.configSummary ? `Configuration: ${manifest.authoring.configSummary}` : void 0,
+		fixedSurfaces.length > 0 ? `Fixed content surfaces: ${fixedSurfaces.map((surface) => surface.key).join(", ")}.` : "Fixed content surfaces: none.",
+		patternedSurfaces.length > 0 ? `Dynamic content surfaces: ${patternedSurfaces.map((surface) => surface.key).join(", ")}.` : void 0,
+		kind === "create-item" && requiredSurfaces.length > 0 ? `Required on creation: ${requiredSurfaces.map((surface) => surface.key).join(", ")}.` : void 0,
+		manifest.referenceTopics?.length ? `Load a dedicated reference only when needed: ${manifest.referenceTopics.join(", ")}.` : void 0
+	].filter((line) => Boolean(line));
+	if (kind === "create-item") lines.push("", "Creation scope: put the complete initial item structure, configuration, and visible translations in this create-item operation. Operations that edit an item by itemId target items already present in the immutable live snapshot; do not create an empty item and then target its new id with option or field editing operations in the same response.");
+	return lines.join("\n");
+};
+const formatSurveyOperationContractReference = (kind, options = {}) => {
+	const { $schema: _schemaVersion, ...contract } = z.toJSONSchema(surveyOperationSchemasByKind[kind], {
+		io: "input",
+		reused: "inline",
+		unrepresentable: "any"
+	});
+	const detail = options.detail ?? "compact";
+	const renderedContract = detail === "full" ? contract : compactJsonSchema(contract);
+	const itemCapability = options.itemCapability;
+	return [
+		`# \`${kind}\` operation contract`,
+		"",
+		"This JSON Schema is generated from the structural validator used by `survey_change`; it is",
+		"the canonical field shape. Cross-field and snapshot-dependent rules are enforced when the",
+		"proposal is validated. The tool may normalize limited schema-near shorthand, but prefer this",
+		"canonical form.",
+		detail === "compact" ? "This compact view preserves the operation structure while omitting deeply nested value schemas. Request detail \"full\" only for protocol debugging; load a focused rich-text, expression, form, or item-type reference for authoring guidance." : "This full view is intended for protocol debugging and may be large.",
+		"",
+		"```json",
+		JSON.stringify(renderedContract, null, 2),
+		"```",
+		...itemCapability ? ["", formatItemCapabilityProfile(itemCapability, kind)] : []
+	].join("\n");
+};
+//#endregion
 //#region src/server/tools/tool-model-output.ts
 const FALLBACK_MODEL_TEXT = "The tool returned no model-readable output. Review the tool arguments and retry with valid values.";
 const unwrapToolOutput$1 = (value) => value && typeof value === "object" && "output" in value && value.output !== void 0 ? value.output : value;
@@ -32,16 +112,20 @@ const TOOL_ID$10 = "survey_authoring_reference";
 const topicSchema = z.string().min(1).max(120);
 const surveyAuthoringReferenceTool = createTool({
 	id: TOOL_ID$10,
-	description: "Load one narrow CASE survey authoring reference or an installed item capability's reference. For a capability-owned reference, provide both itemType and the reference topic advertised in the capability manifest.",
+	description: "Load one narrow CASE authoring reference. With topic \"item-types\", pass itemType to load only that type. For a survey_change operation, use topic \"assistant-operations\" with operationKind and optionally itemType to compose the structural contract with that installed item capability. Compact detail is the authoring default; full detail is only for protocol debugging.",
 	inputSchema: z.object({
 		topic: topicSchema.describe("The narrow authoring reference to load."),
-		itemType: z.string().min(1).max(120).optional().describe("Installed custom item type that owns this reference, when applicable."),
+		itemType: z.string().min(1).max(120).optional().describe("Installed item type to focus. With topic \"item-types\", returns only that item type section instead of the combined reference."),
+		operationKind: z.string().min(1).max(120).optional().describe("For topic assistant-operations, return only this operation's generated canonical field contract."),
+		detail: z.enum(SURVEY_OPERATION_CONTRACT_DETAIL_LEVELS).optional().describe("Contract detail for assistant-operations. Use \"compact\" for authoring and \"full\" only for protocol debugging."),
 		reason: z.string().max(500).optional().describe("Short reason this reference is needed.")
 	}),
 	outputSchema: z.object({
 		ok: z.boolean(),
 		topic: topicSchema,
 		itemType: z.string().optional(),
+		operationKind: z.string().optional(),
+		detail: z.enum(SURVEY_OPERATION_CONTRACT_DETAIL_LEVELS).optional(),
 		title: z.string(),
 		content: z.string()
 	}),
@@ -53,22 +137,75 @@ const surveyAuthoringReferenceTool = createTool({
 		openWorldHint: false
 	} },
 	execute: async (inputData, context) => {
-		const builtInEntry = surveyAuthoringReferenceTopics.includes(inputData.topic) ? surveyAuthoringReferences[inputData.topic] : void 0;
+		const contractDetail = inputData.detail ?? "compact";
 		const engineContext = context?.requestContext?.get("engineContext");
+		const itemCapability = inputData.itemType ? engineContext?.trustedCapabilities?.byItemType.get(inputData.itemType)?.manifest ?? engineContext?.capabilities.itemTypes.find((entry) => entry.itemType === inputData.itemType) : void 0;
+		if (inputData.operationKind && inputData.topic !== "assistant-operations") return {
+			ok: false,
+			topic: inputData.topic,
+			itemType: inputData.itemType,
+			operationKind: inputData.operationKind,
+			title: "Operation contract unavailable",
+			content: "operationKind is supported only with topic assistant-operations."
+		};
+		if (inputData.operationKind) {
+			if (!isSurveyOperationKind(inputData.operationKind)) return {
+				ok: false,
+				topic: inputData.topic,
+				operationKind: inputData.operationKind,
+				detail: contractDetail,
+				title: "Operation contract unavailable",
+				content: `No built-in survey_change operation named "${inputData.operationKind}" is available.`
+			};
+			if (inputData.itemType && !itemCapability) return {
+				ok: false,
+				topic: inputData.topic,
+				itemType: inputData.itemType,
+				operationKind: inputData.operationKind,
+				detail: contractDetail,
+				title: "Item capability unavailable",
+				content: `No installed survey item capability named "${inputData.itemType}" is available.`
+			};
+			if (itemCapability && !itemCapability.supportedOperations.includes(inputData.operationKind)) return {
+				ok: false,
+				topic: inputData.topic,
+				itemType: inputData.itemType,
+				operationKind: inputData.operationKind,
+				detail: contractDetail,
+				title: "Operation unsupported for item type",
+				content: `Item type "${itemCapability.itemType}" does not support survey_change operation "${inputData.operationKind}".`
+			};
+			return {
+				ok: true,
+				topic: inputData.topic,
+				itemType: inputData.itemType,
+				operationKind: inputData.operationKind,
+				detail: contractDetail,
+				title: itemCapability ? `${inputData.operationKind} for ${itemCapability.displayName}` : `${inputData.operationKind} operation contract`,
+				content: formatSurveyOperationContractReference(inputData.operationKind, {
+					detail: contractDetail,
+					itemCapability
+				})
+			};
+		}
+		const builtInEntry = surveyAuthoringReferenceTopics.includes(inputData.topic) ? surveyAuthoringReferences[inputData.topic] : void 0;
 		const capability = inputData.itemType ? engineContext?.trustedCapabilities?.byItemType.get(inputData.itemType) : void 0;
 		const capabilityReference = inputData.itemType ? resolveAssistantCapabilityReference({
 			capabilities: engineContext?.trustedCapabilities,
 			itemType: inputData.itemType,
 			topic: inputData.topic
 		}) : void 0;
-		const entry = capabilityReference ? {
+		const focusedBuiltInItemTypeReference = inputData.topic === "item-types" && inputData.itemType ? getBuiltInItemTypeAuthoringReference(inputData.itemType) : void 0;
+		const capabilityEntry = capabilityReference ? {
 			title: capabilityReference.title ?? `${capability?.manifest.displayName} authoring`,
 			content: capabilityReference.markdown
-		} : builtInEntry;
+		} : void 0;
+		const entry = focusedBuiltInItemTypeReference ?? capabilityEntry ?? builtInEntry;
 		if (!entry) return {
 			ok: false,
 			topic: inputData.topic,
 			itemType: inputData.itemType,
+			operationKind: inputData.operationKind,
 			title: "Reference unavailable",
 			content: inputData.itemType ? `No reference named "${inputData.topic}" is installed for item type "${inputData.itemType}".` : `No built-in reference named "${inputData.topic}" is available.`
 		};
@@ -76,6 +213,7 @@ const surveyAuthoringReferenceTool = createTool({
 			ok: true,
 			topic: inputData.topic,
 			itemType: inputData.itemType,
+			operationKind: inputData.operationKind,
 			title: entry.title,
 			content: entry.content
 		};
@@ -85,14 +223,30 @@ const surveyAuthoringReferenceTool = createTool({
 //#endregion
 //#region src/server/tools/survey-change-tool.ts
 const TOOL_ID$9 = "survey_change";
+const OPERATIONS_DESCRIPTION = [
+	"Typed survey operation objects to validate and package as one undoable change. Every object uses discriminator \"kind\", never \"type\".",
+	"For an unfamiliar canonical shape, load survey_authoring_reference with topic \"assistant-operations\" and operationKind; it returns only that operation schema, generated from the validator.",
+	"Any translations owned by an operation must be inside that same operation object. Never put translations beside the survey_change operations array.",
+	"Create items with { kind: \"create-item\", target: { parentItemId, index? }, item: { id?, key, itemType, config }, translations? }. Put respondent content in top-level translations and item settings in item.config.",
+	"Use update-item-translation with itemId, locale, contentKey, and plainText for ordinary text or content for a complete structured value. Item titles and option/field labels are translations, not item labels.",
+	"Item-editing operations target items already present in the immutable live snapshot. For a new item, put its complete initial options, fields, config, translations, and embedded expressions directly in create-item; do not create it empty and target its new id later in the response.",
+	"For an existing choice item, use add-choice-option with itemId, optional locale/index, and option: { id?, key?, label }; label is a plain string and creates its translation.",
+	"Every reorder replaces the complete inspected list: reorder-choice-options uses optionIds, reorder-form-field-groups uses groupIds, and reorder-items uses itemIds for every direct child. Include every existing entry exactly once in desired order.",
+	`Use update-item-color only with a supported swatch. ${`Allowed editor item-color swatches: ${SURVEY_EDITOR_ITEM_COLORS.join(", ")}. Use one of these exact values for update-item-color; do not wait for validation feedback to choose a swatch.`}`,
+	"Use patch-item-config with itemId and plural patches whose JSON Pointer paths are relative to that item config root.",
+	"Use update-placed-image only for an image already present in the immutable snapshot. For a new item, embed the complete image block directly in create-item translations.",
+	"When deleting referenced images and assets, include every reference-removal operation and remove-image-asset last in the same operations array.",
+	"Raw fallback is one { kind: \"survey-json-patch\", patches } operation containing all related survey-rooted edits; it must be the only operation in the call.",
+	"Keep proposals bounded; split oversized work into independent complete change calls."
+].join(" ");
 const inputSchema$9 = z.object({
 	intent: z.string().min(1).max(500).describe("The concrete survey change requested by the user."),
 	summary: z.string().min(1).max(500).describe("Short user-facing summary of the intended survey change."),
-	operations: z.array(z.unknown()).min(1).max(200).describe("Assistant operation objects to validate and package as one undoable change. Every operation uses the exact discriminator field \"kind\", never \"type\". Canonical create shape: { kind: \"create-item\", target: { parentItemId, index? }, item: { id, key, itemType, config }, translations?: [{ locale, contentKey, plainText } | { locale, contentKey, content }] }. Put parentItemId in target, respondent content in top-level translations, and item-type settings in item.config. When creating a new item that contains an imported or external image, put the complete richText content including its image block directly in create-item.translations[].content in the same call; never create a placeholder and then call update-placed-image because the new item is absent from the immutable snapshot. When deleting referenced images and their assets, include all reference-removal operations and remove-image-asset in this same operations array, with remove-image-asset last; do not split that dependency across survey_change and survey_asset. For a choice item, config.options entries use id and optional key/embeddedForm only; option labels are top-level translations at options.<optionId>.label. Canonical presentation shapes are { kind: \"update-item-label\", itemId, itemLabel } for the editor-only label and { kind: \"update-item-color\", itemId, color } for a supported editor swatch. Across editor views, unqualified labels for items/questions mean update-item-label; question titles and option/field labels are respondent-visible translations. Canonical item config shape: { kind: \"patch-item-config\", itemId, patches: [{ op, path, value? }] }, where paths are relative to that item config root. Inspect the item and load its capability reference first. Canonical add-choice-option shape: { kind: \"add-choice-option\", itemId, locale?, index?, option: { id?, key?, label: \"visible text\" } }; label is a plain string, and this operation creates its translation. Canonical text-update shape: { kind: \"update-item-translation\", itemId, locale, contentKey, plainText } for ordinary text; content is only a structured Content object for meaningful formatting. To edit one image already placed in rich text, use { kind: \"update-placed-image\", itemId, locale, contentKey, imageIndex, expectedAssetId?, changes } where imageIndex counts only image blocks from zero. changes can set a local asset source or an external URL and can update alt, caption, width, height, maxWidth, maxHeight, and alignment; null removes an optional property. This changes the rendered placement, while update-image-asset-metadata changes only global asset metadata. Canonical raw shape: { kind: \"survey-json-patch\", patches: [{ op, path, value? }] }; it must be the only operation and all related raw edits belong in its plural patches array, never patch. Patch paths are rooted at the survey, for example /surveyItems/<index>/config or /translations/<locale>. Keep proposals bounded; if validation says there are too many operations, split the same work into independent smaller change calls. Use compact typed operations for common edits, patch-item-config for item-local config, and one survey-json-patch operation for survey-wide raw edits."),
+	operations: z.array(z.unknown()).min(1).max(200).describe(OPERATIONS_DESCRIPTION),
 	continuationMode: z.enum(SURVEY_CHANGE_CONTINUATION_MODES).nullish().transform((value) => value ?? void 0).describe(`${SURVEY_CHANGE_CONTINUATION_DESCRIPTION} Omit this field instead of sending null.`),
 	inspectedContext: z.array(z.string().max(240)).max(20).nullish().transform((value) => value ?? void 0).describe("Optional item ids, paths, or references inspected before proposing this change."),
 	notes: z.string().max(1e3).nullish().transform((value) => value ?? void 0).describe("Optional implementation notes for validation/debugging; not shown as persisted survey content.")
-});
+}).strict();
 const rejectedOperationParseEvent = ({ issueText, summary, turnId }) => ({
 	protocolVersion: 1,
 	id: randomUUID(),
@@ -150,7 +304,9 @@ const summarizeValidation = (event) => {
 	const lines = [`${event.status === "validated" ? "Validated" : "Rejected"} survey change: ${event.summary}`, `Change id: ${event.id}`];
 	if (event.operations.length > 0) lines.push(`Operations: ${event.operations.map((operation) => operation.kind).join(", ")}`);
 	if (event.status === "rejected") {
-		lines.push("Apply status: this turn is blocked and will authorize no survey changes unless a later complete proposal validates with continuationMode \"replace\".");
+		lines.push("Apply status: blocked; this candidate is not authorized.");
+		if (event.recovery?.requiredContinuationMode) lines.push(`Required recovery: resubmit the complete intended proposal with continuationMode "${event.recovery.requiredContinuationMode}". No survey change from this turn can be authorized until that replacement validates.`);
+		else if (event.recovery) lines.push(`Required recovery: resubmit the complete proposal with an explicit continuationMode (${event.recovery.allowedContinuationModes.join(" or ")}).`);
 		if (event.operations.length > 0) {
 			const checklist = event.operations.slice(0, 24).map(describeOperationTarget);
 			lines.push(`Unapplied target sample (${checklist.length} of ${event.operations.length}):\n${checklist.map((target) => `- ${target}`).join("\n")}`);
@@ -168,8 +324,6 @@ const summarizeValidation = (event) => {
 		const issueCodes = new Set(event.validation.issues.map((issue) => issue.code));
 		if (issueCodes.has("missing-create-content") || issueCodes.has("missing-field-groups-wrapper") || issueCodes.has("missing-choice-options") || issueCodes.has("missing-choice-option-labels")) lines.push("Recovery hint: load the assistant-operations reference, then retry the complete create-item proposal with continuationMode \"replace\". Put visible text in top-level translations[] beside item, config inside item.config, choice options in item.config.options, and form fields inside item.config.fieldGroups[].fields. Every choice option id needs a matching top-level translation whose contentKey is options.<optionId>.label.");
 		if (issueCodes.has("too-many-operations")) lines.push("Recovery hint: keep the same inspected survey context and immediately split these edits into smaller survey_change calls. Use continuationMode \"replace\" on the first repaired chunk, then \"append\" on every later independent chunk. Do not claim that a new snapshot is needed unless a tool explicitly reported a missing snapshot.");
-		if (issueCodes.has("change-mode-required")) lines.push("Recovery hint: retry the complete intended proposal with continuationMode \"append\" for independent additional work or \"replace\" for a correction. Nothing from the ambiguous sequence is currently authorized.");
-		if (issueCodes.has("change-mode-repair-required")) lines.push("Recovery hint: the turn remains blocked. Retry the complete intended proposal with continuationMode \"replace\". Only a validated replacement clears the block; after that, use \"append\" for later independent chunks.");
 	}
 	if (event.validation.warnings.length > 0) {
 		lines.push("Warnings:");
@@ -179,7 +333,7 @@ const summarizeValidation = (event) => {
 };
 const surveyChangeTool = createTool({
 	id: TOOL_ID$9,
-	description: "Validate and queue one final, bounded, undoable survey change. This is not a dry run and does not mutate the live snapshot during the response. Put related operations and newly created dependencies in one call, in dependency order; embed expressions on new dependent items. Omit continuationMode only on the first mutation call in a turn; every later mutation call must use \"append\" for independent additional work or \"replace\" for a correction. Every operation uses \"kind\". A create-item has top-level target, item, and translations.",
+	description: "Validate and queue one final, bounded, undoable survey change. This is not a dry run and does not mutate the live snapshot during the response. The live snapshot is immutable: item-editing operations target existing items, while each create-item must contain that new item's complete initial config, content, options, fields, and embedded expressions. Multiple create-item operations may be ordered by dependency in one proposal. Omit continuationMode only on the first mutation call in a turn; every later mutation call must use \"append\" for independent additional work or \"replace\" for a correction. Every operation uses \"kind\".",
 	inputSchema: inputSchema$9,
 	outputSchema: surveyChangeSetSchema,
 	mcp: { annotations: {
@@ -238,7 +392,7 @@ const inputSchema$8 = z.object({
 	mutations: z.array(z.record(z.string(), z.unknown())).min(1).max(40).optional().describe("For prepare: expression mutation objects using kebab-case kind names. Item visibility shape: { kind: \"set-item-display-condition\", itemId: \"<existing-item-id>\", expression: { type: \"function\", functionName: \"eq\", arguments: [...] } }. expression is always CASE expression JSON, never a string or expression-language snippet. Other supported kinds set/clear component display/disabled conditions, validation expressions, prefills, and template values."),
 	continuationMode: continuationModeSchema,
 	inspectedContext: z.array(z.string().max(240)).max(20).optional()
-}).superRefine((value, ctx) => {
+}).strict().superRefine((value, ctx) => {
 	if (value.action !== "prepare") return;
 	if (!value.intent) ctx.addIssue({
 		code: z.ZodIssueCode.custom,
@@ -260,6 +414,7 @@ const contextOutputSchema = z.object({
 	ok: z.boolean(),
 	action: z.literal("context"),
 	modelSummary: z.string(),
+	listOrdering: z.record(z.string(), z.string()).describe("Meaning of each returned list. Expression references are not positional."),
 	responseSlots: z.array(z.object({
 		ref: z.string(),
 		valueType: z.string().optional()
@@ -296,14 +451,15 @@ const rejectedEvent = ({ issues, summary, turnId, warnings = [] }) => ({
 const summarizeDraftEvent = (event) => {
 	const lines = [`${event.status === "validated" ? "Validated" : "Rejected"} expression change: ${event.summary}`, `Change id: ${event.id}`];
 	if (event.operations.length > 0) lines.push(`Operations: ${event.operations.map((operation) => operation.kind).join(", ")}`);
-	if (event.status === "rejected") lines.push("Apply status: this turn is blocked and will authorize no survey changes unless a later complete proposal validates with continuationMode \"replace\".");
+	if (event.status === "rejected") {
+		lines.push("Apply status: blocked; this candidate is not authorized.");
+		if (event.recovery?.requiredContinuationMode) lines.push(`Required recovery: resubmit the complete intended proposal with continuationMode "${event.recovery.requiredContinuationMode}". No survey change from this turn can be authorized until that replacement validates.`);
+		else if (event.recovery) lines.push(`Required recovery: resubmit the complete proposal with an explicit continuationMode (${event.recovery.allowedContinuationModes.join(" or ")}).`);
+	}
 	if (event.supersedesChangeIds?.length) lines.push(event.status === "validated" ? `Queue: replaces ${event.supersedesChangeIds.length} earlier candidate proposal(s) from this response.` : `Queue: discarded ${event.supersedesChangeIds.length} earlier candidate proposal(s); their work is not retained or authorized.`);
 	if (event.validation.issues.length > 0) {
 		lines.push("Issues:");
 		for (const issue of event.validation.issues) lines.push(`- ${issue.code}: ${issue.message}`);
-		const issueCodes = new Set(event.validation.issues.map((issue) => issue.code));
-		if (issueCodes.has("change-mode-required")) lines.push("Recovery hint: retry the complete intended proposal with continuationMode \"append\" for independent additional work or \"replace\" for a correction. Nothing from the ambiguous sequence is currently authorized.");
-		if (issueCodes.has("change-mode-repair-required")) lines.push("Recovery hint: the turn remains blocked. Retry the complete intended proposal with continuationMode \"replace\". Only a validated replacement clears the block; after that, use \"append\" for later independent chunks.");
 	}
 	if (event.validation.warnings.length > 0) {
 		lines.push("Warnings:");
@@ -345,11 +501,17 @@ const buildContextOutput = (snapshot, input) => {
 			"Display, disabled, validation, and prefill.when expressions must return boolean.",
 			"Use response refs exactly as listed and check their value types before choosing functions.",
 			"For choice options: use eq(response reference, reference const) when the slot type is reference; use list_contains(response reference[], reference const) only when the slot type is reference[].",
+			"Response-slot order: set-like deterministic snapshot construction order; it has no survey or respondent-visible meaning.",
 			`Response slots (${responseSlots.length}): ${responseSlots.slice(0, 80).map((slot) => `${slot.ref}${slot.valueType ? `:${slot.valueType}` : ""}`).join(", ")}`,
 			responseSlots.length > 80 ? "Response slot list truncated in summary; inspect context result for more." : void 0,
 			"Functions: and, or, not, eq, gt, gte, lt, lte, in_range, list_contains, sum, min, max, str_eq, date_eq.",
 			expressionLocations ? `Existing expression locations: ${expressionLocations.filter((entry) => entry.locations.length > 0).map((entry) => `${entry.key}(${entry.itemId}) -> ${entry.locations.join("|")}`).join("; ") || "none"}` : void 0
 		].filter((line) => Boolean(line)).join("\n"),
+		listOrdering: {
+			responseSlots: "Set-like deterministic snapshot construction order; position has no survey or respondent-visible meaning.",
+			expressionLocations: "Stored surveyItems array order; locations within an item are grouped by expression surface, not ranked or respondent-visible order.",
+			"expressionLocations[].locations": "Grouped by expression surface (root, components, validations, prefills); position has no semantic meaning."
+		},
 		responseSlots,
 		...expressionLocations ? { expressionLocations } : {}
 	};
@@ -375,6 +537,7 @@ const surveyExpressionTool = createTool({
 				ok: false,
 				action: "context",
 				modelSummary: "No live editor snapshot is available for expression work.",
+				listOrdering: { responseSlots: "Set-like; unavailable because no live snapshot was provided." },
 				responseSlots: []
 			};
 			const { changeCollector, turnId } = requireSurveyAssistantTurnState(requestContext);
@@ -487,6 +650,7 @@ const outputSchema$6 = z.object({
 	revision: z.number().int().nonnegative().optional(),
 	contentHash: z.string().optional(),
 	scopes: z.array(contextScopeSchema).optional(),
+	listOrdering: z.record(z.string(), z.string()).optional().describe("Meaning of each returned list. A list is positional only when its entry says so."),
 	summary: z.object({
 		sessionId: z.string().nullable(),
 		view: z.string(),
@@ -528,6 +692,7 @@ const outputSchema$6 = z.object({
 		returned: z.number().int().nonnegative(),
 		nextCursor: z.string().optional(),
 		truncated: z.boolean(),
+		ordering: z.string(),
 		items: z.array(itemSummarySchema),
 		note: z.string().optional()
 	}).optional(),
@@ -538,6 +703,7 @@ const outputSchema$6 = z.object({
 		returned: z.number().int().nonnegative(),
 		nextCursor: z.string().optional(),
 		truncated: z.boolean(),
+		ordering: z.string(),
 		slots: z.array(z.string()),
 		note: z.string().optional()
 	}).optional(),
@@ -691,6 +857,7 @@ const buildOutline = (snapshot, input) => {
 		returned: page.items.length,
 		nextCursor: page.nextCursor,
 		truncated: page.truncated,
+		ordering: strategy === "focused-snapshot-outline" ? "Survey-tree preorder: configured group-child order is preserved; unparented items are appended by item id." : strategy === "direct-children" ? "Stored group-child order; this is not a stable respondent-visible order if that group shuffles children." : strategy === "query-match" ? "Survey-tree preorder after filtering by the query; this is not relevance-ranked." : "Relationship grouping for the focused item, not a single positional survey order.",
 		items: page.items,
 		note
 	};
@@ -707,6 +874,7 @@ const buildResponseSlots = (snapshot, input) => {
 		returned: page.items.length,
 		nextCursor: page.nextCursor,
 		truncated: page.truncated,
+		ordering: "Set-like response references in deterministic snapshot construction order; do not interpret their position as survey or respondent order.",
 		slots: page.items
 	};
 };
@@ -716,9 +884,9 @@ const summarizeForModel$3 = (output) => {
 	if (output.summary) {
 		const selected = output.summary.selectedItemId ?? "none";
 		const surveyKey = output.summary.surveyKey ?? "not set";
-		lines.push(`Summary: view=${output.summary.view}; selectedItemId=${selected}; locale=${output.summary.selectedLocale}; surveyKey=${surveyKey}; itemCount=${output.summary.itemCount}.`);
+		lines.push(`Summary: view=${output.summary.view}; selectedItemId=${selected}; locale=${output.summary.selectedLocale}; surveyKey=${surveyKey}; itemCount=${output.summary.itemCount} (excluding the structural root group).`);
 		if (output.summary.rootItem) lines.push(`Root group for top-level create-item target.parentItemId: ${output.summary.rootItem.fullKey} (id=${output.summary.rootItem.itemId}, key=${output.summary.rootItem.key}).`);
-		lines.push(`Outline access: ${output.summary.outlineItemCount} item(s) are pageable.`);
+		lines.push(`Outline access: ${output.summary.outlineItemCount} item(s), including the structural root group, are pageable.`);
 		const creatableDetails = output.summary.itemTypeDetails.filter((entry) => entry.create === "deterministic").map((entry) => {
 			const primarySurface = entry.contentSurfaces.find((surface) => surface.role === "primary");
 			const fixedSurfaces = entry.contentSurfaces.filter((surface) => !surface.pattern).map((surface) => surface.key);
@@ -726,7 +894,8 @@ const summarizeForModel$3 = (output) => {
 			const contentKeys = [
 				primarySurface ? `primary=${primarySurface.key}` : void 0,
 				fixedSurfaces.length ? `visible=${fixedSurfaces.join("|")}` : void 0,
-				patterns.length ? `dynamic=${patterns.join("|")}` : void 0
+				patterns.length ? `dynamic=${patterns.join("|")}` : void 0,
+				entry.authoring?.compactHint
 			].filter((value) => Boolean(value)).join("; ");
 			return contentKeys ? `${entry.itemType} (${contentKeys})` : entry.itemType;
 		});
@@ -739,9 +908,13 @@ const summarizeForModel$3 = (output) => {
 	if (output.outline) {
 		lines.push(`Outline (${output.outline.strategy}${output.outline.mode ? `, mode=${output.outline.mode}` : ""}): ${output.outline.returned}/${output.outline.totalAvailable} rows returned.`);
 		for (const item of output.outline.items) lines.push(`- ${item.fullKey} (${item.itemType})${item.itemLabel ? ` - ${item.itemLabel}` : ""}`);
+		lines.push(`Outline order: ${output.outline.ordering}`);
 		if (output.outline.nextCursor) lines.push(`More outline rows are available with cursor ${output.outline.nextCursor}.`);
 	}
-	if (output.responseSlots) lines.push(output.responseSlots.available ? `Response slots: ${output.responseSlots.slots.join(", ") || "none"}` : `Response slots unavailable: ${output.responseSlots.note ?? "not indexed"}.`);
+	if (output.responseSlots) {
+		lines.push(output.responseSlots.available ? `Response slots: ${output.responseSlots.slots.join(", ") || "none"}` : `Response slots unavailable: ${output.responseSlots.note ?? "not indexed"}.`);
+		if (output.responseSlots.available) lines.push(`Response-slot order: ${output.responseSlots.ordering}`);
+	}
 	if (output.uiContext) lines.push(`UI context: activeSurface=${output.uiContext.activeSurface ?? "not provided"}; openPanels=${output.uiContext.openPanels.join(", ") || "none"}; highlights=${output.uiContext.highlights.map((entry) => entry.label ?? entry.itemId ?? entry.componentId ?? entry.kind).join(", ") || "none"}.`);
 	if (output.history) lines.push(`Recent editor history (${output.history.currentIndex + 1}/${output.history.totalEntries}): ${output.history.recent.map((entry) => `${entry.index}:${entry.label}${entry.isCurrent ? " [current]" : ""}`).join("; ") || "none"}.`);
 	return lines.join("\n");
@@ -772,11 +945,32 @@ const surveyGetCurrentContextTool = createTool({
 			scopes: input.scopes
 		};
 		const scopes = unique(input.scopes);
+		const listOrdering = {};
+		if (scopes.includes("summary")) Object.assign(listOrdering, {
+			"summary.recentItemIds": "Most-recent-first UI history; not survey structure.",
+			"summary.locales": "Selected locale first, then remaining source locale order; locale position has no survey meaning.",
+			"summary.availableItemTypes": "Capability registry order; treat as a set of available types.",
+			"summary.deterministicCreateItemTypes": "Capability registry order; treat as a set of available types.",
+			"summary.itemTypeDetails": "Capability registry order; treat as a set of available type definitions."
+		});
+		if (scopes.includes("selected-item")) Object.assign(listOrdering, {
+			"selectedItem.pathItems": "Root-to-selected survey-tree path.",
+			"selectedItem.siblingItems": "Source survey item storage order; not necessarily respondent-visible order.",
+			"selectedItem.childItems": "Stored group-child order when the focused item is a group.",
+			"selectedItem.translationSnippets": "Grouped by locale and then source translation-key order; not positional survey content.",
+			"selectedItem.descendantItems": "Depth-first survey-tree traversal from the selected item."
+		});
+		if (scopes.includes("ui-context")) Object.assign(listOrdering, {
+			"uiContext.openPanels": "UI-provided set-like list; position has no meaning.",
+			"uiContext.highlights": "UI-provided set-like list; position has no meaning."
+		});
+		if (scopes.includes("history")) listOrdering["history.recent"] = "Chronological editor history, oldest to newest within this returned window.";
 		const output = {
 			ok: true,
 			revision: snapshot.version.revision,
 			contentHash: snapshot.version.contentHash,
-			scopes
+			scopes,
+			...Object.keys(listOrdering).length > 0 ? { listOrdering } : {}
 		};
 		if (scopes.includes("summary")) output.summary = buildSummary(snapshot);
 		if (scopes.includes("selected-item")) output.selectedItem = buildSelectedItem(snapshot, input);
@@ -814,6 +1008,7 @@ const outputSchema$5 = z.object({
 	translations: z.array(translationEntrySchema).optional(),
 	surveyChildren: z.array(itemSummarySchema).optional(),
 	surveyChildrenTruncated: z.boolean().optional(),
+	listOrdering: z.record(z.string(), z.string()).optional().describe("Meaning of each returned list. A list is positional only when its entry says so."),
 	configDetails: itemConfigDetailsSchema.optional(),
 	capabilityDetails: z.object({
 		summary: z.string(),
@@ -824,21 +1019,21 @@ const summarizeConfigDetails = (configDetails) => {
 	const lines = [`Config details (${configDetails.kind}): ${configDetails.summary.join("; ")}`];
 	if (configDetails.mainResponseSlotId) lines.push(`Main response slot: ${configDetails.mainResponseSlotId}`);
 	for (const option of configDetails.choiceOptions ?? []) {
-		lines.push(`- option ${option.key ?? option.id} (id=${option.id}, labelContentKey=${option.labelContentKey})`);
+		lines.push(`- ${option.position}. option ${option.key ?? option.id} (id=${option.id}, labelContentKey=${option.labelContentKey})`);
 		if (option.embeddedFormItemId || option.embeddedFormFieldGroupCount) {
 			lines.push(`  embedded form: itemId=${option.embeddedFormItemId ?? "inline"}, fieldGroups=${option.embeddedFormFieldGroupCount ?? 0}`);
 			if (option.embeddedFormTranslationPrefix || option.embeddedFormResponseSlotPrefix) lines.push(`  embedded form keys: translationPrefix=${option.embeddedFormTranslationPrefix ?? "n/a"}, responseSlotPrefix=${option.embeddedFormResponseSlotPrefix ?? "n/a"}`);
 		}
 	}
 	for (const group of configDetails.formFieldGroups ?? []) {
-		lines.push(`- field group ${group.id}: ${group.fieldCount} field(s), titleContentKey=${group.titleContentKey}, layout=${group.layout.base}/${group.layout.xs}/${group.layout.sm}/${group.layout.md}/${group.layout.xl}`);
+		lines.push(`- ${group.position}. field group ${group.id}: ${group.fieldCount} field(s), titleContentKey=${group.titleContentKey}, layout=${group.layout.base}/${group.layout.xs}/${group.layout.sm}/${group.layout.md}/${group.layout.xl}`);
 		if (group.hasDisplayCondition !== void 0) lines.push(`  hasDisplayCondition=${group.hasDisplayCondition ? "true" : "false"}`);
 		for (const field of group.fields) {
-			lines.push(`  - field ${field.key} (${field.type}, id=${field.id}, responseSlot=${field.responseSlotId}, labelContentKey=${field.labelContentKey})`);
+			lines.push(`  - ${field.position}. field ${field.key} (${field.type}, id=${field.id}, responseSlot=${field.responseSlotId}, labelContentKey=${field.labelContentKey})`);
 			lines.push(`    extra content keys: description=${field.descriptionContentKey}, error=${field.errorContentKey}${field.placeholderContentKey ? `, placeholder=${field.placeholderContentKey}` : ""}${field.unitContentKey ? `, unit=${field.unitContentKey}` : ""}${field.checkedLabelContentKey ? `, checkedLabel=${field.checkedLabelContentKey}` : ""}${field.uncheckedLabelContentKey ? `, uncheckedLabel=${field.uncheckedLabelContentKey}` : ""}`);
 			if (field.validationTypes?.length) lines.push(`    validations: ${field.validationTypes.join(", ")}`);
 			if (field.validationMessageContentKeys?.length) lines.push(`    validation message keys: ${field.validationMessageContentKeys.join(", ")}`);
-			if (field.selectOptions?.length) lines.push(`    select options: ${field.selectOptions.map((option) => `${option.value ?? option.id} (${option.labelContentKey})`).join(", ")}`);
+			if (field.selectOptions?.length) lines.push(`    select options: ${field.selectOptions.map((option) => `${option.position}. ${option.value ?? option.id} (${option.labelContentKey})`).join(", ")}`);
 		}
 	}
 	return lines;
@@ -854,7 +1049,10 @@ const summarizeForModel$2 = (output) => {
 		for (const child of output.surveyChildren) lines.push(`- ${child.fullKey} (${child.itemType})${child.itemLabel ? ` - ${child.itemLabel}` : ""}`);
 		if (output.surveyChildrenTruncated) lines.push("More children exist than were returned; narrow down or raise childrenLimit.");
 	}
-	if (output.configDetails) lines.push(...summarizeConfigDetails(output.configDetails));
+	if (output.configDetails) {
+		if (output.configDetails.listOrdering) for (const [list, meaning] of Object.entries(output.configDetails.listOrdering)) lines.push(`List order (${list}): ${meaning}`);
+		lines.push(...summarizeConfigDetails(output.configDetails));
+	}
 	if (output.capabilityDetails) {
 		lines.push(`Item capability: ${output.capabilityDetails.summary}`);
 		if (output.capabilityDetails.details !== void 0) lines.push(`Capability details: ${JSON.stringify(output.capabilityDetails.details)}`);
@@ -894,10 +1092,16 @@ const surveyGetItemDetailsTool = createTool({
 			ok: false,
 			reason: `No item matching "${input.itemId}" (by itemId, key, or fullKey) was found in the current context snapshot.`
 		};
+		const rawItem = rawItemsById.get(item.itemId);
+		const rawConfig = rawItem?.config && typeof rawItem.config === "object" && !Array.isArray(rawItem.config) ? rawItem.config : void 0;
 		const output = {
 			ok: true,
 			item,
-			translations: buildItemTranslationEntries(snapshot, item.itemId, input)
+			translations: buildItemTranslationEntries(snapshot, item.itemId, input),
+			listOrdering: {
+				translations: "Grouped by locale and then source translation-key order; this list is not positional survey content.",
+				surveyChildren: rawConfig?.shuffleItems === true ? "Stored group-child order; respondents see shuffled children, so this is not a stable respondent-visible order." : "Stored group-child order; this is the respondent-visible order when the parent is a group."
+			}
 		};
 		if (input.includeSurveyChildren) {
 			const allChildren = findDirectChildrenByFullKey(getKeyIndexEntries(snapshot), outlineById, item.fullKey);
@@ -906,15 +1110,14 @@ const surveyGetItemDetailsTool = createTool({
 			output.surveyChildrenTruncated = allChildren.length > limit;
 		}
 		if (input.includeItemConfig) {
-			const rawItem = rawItemsById.get(item.itemId);
 			output.configDetails = rawItem ? buildItemConfigDetails(rawItem) : void 0;
 			output.capabilityDetails = rawItem ? inspectAssistantItem({
 				capabilities: snapshot.trustedCapabilities,
 				item: rawItem
 			}) : void 0;
 			if (rawItem?.itemType === "choiceItem" && output.configDetails?.choiceOptions) {
-				const rawConfig = rawItem.config && typeof rawItem.config === "object" && !Array.isArray(rawItem.config) ? rawItem.config : void 0;
-				const rawOptions = Array.isArray(rawConfig?.options) ? rawConfig.options : [];
+				const rawChoiceConfig = rawItem.config && typeof rawItem.config === "object" && !Array.isArray(rawItem.config) ? rawItem.config : void 0;
+				const rawOptions = Array.isArray(rawChoiceConfig?.options) ? rawChoiceConfig.options : [];
 				for (const option of output.configDetails.choiceOptions) {
 					const rawOption = rawOptions.find((candidate) => candidate && typeof candidate === "object" && "id" in candidate && candidate.id === option.id);
 					const embeddedFormDetails = buildEmbeddedFormDetails(option, rawOption && typeof rawOption === "object" && "embeddedForm" in rawOption ? rawOption.embeddedForm : void 0);
@@ -950,6 +1153,7 @@ const outputSchema$4 = z.object({
 	reason: z.string().optional(),
 	revision: z.number().int().nonnegative().optional(),
 	contentHash: z.string().optional(),
+	listOrdering: z.record(z.string(), z.string()).optional().describe("Meaning of each returned list. Raw JSON arrays retain their stored order."),
 	overview: z.object({
 		topLevelKeys: z.array(z.string()),
 		surveyItemCount: z.number().int().nonnegative(),
@@ -1101,6 +1305,7 @@ const summarizeForModel$1 = (output) => {
 		for (const item of output.overview.itemPaths.slice(0, 50)) lines.push(`- ${item.path}: ${item.key} (${item.itemType}, id=${item.id})${item.parentId ? ` parent=${item.parentId}` : ""}`);
 		if (output.overview.itemPaths.length > 50) lines.push("More item paths exist; request a specific path for exact raw JSON.");
 	}
+	if (output.listOrdering) for (const [list, meaning] of Object.entries(output.listOrdering)) lines.push(`List order (${list}): ${meaning}`);
 	for (const item of output.items ?? []) {
 		if (!item.found) {
 			lines.push(`${item.identifier}: not found (${item.error ?? "unknown error"})`);
@@ -1149,6 +1354,13 @@ const surveyGetRawSurveyTool = createTool({
 			ok: true,
 			revision: snapshot.version.revision,
 			contentHash: snapshot.version.contentHash,
+			listOrdering: {
+				"overview.topLevelKeys": "Alphabetical key order; not survey content order.",
+				"overview.locales": "Selected locale first, then remaining source locale order; locale position has no survey meaning.",
+				"overview.itemPaths": "Stored surveyItems array order. The numeric segment in each JSON Pointer path is its zero-based stored position; this differs from group-child display order.",
+				values: "Same order as the requested JSON Pointer paths.",
+				items: "Same order as the requested itemIdentifiers."
+			},
 			overview: input.paths || input.itemIdentifiers ? void 0 : buildOverview(snapshot),
 			items: input.itemIdentifiers ? buildItemValues(snapshot, {
 				itemIdentifiers: input.itemIdentifiers,
@@ -1200,6 +1412,7 @@ const outputSchema$3 = z.object({
 	returned: z.number().int().nonnegative().optional(),
 	nextCursor: z.string().optional(),
 	truncated: z.boolean().optional(),
+	ordering: z.string().optional().describe("How results and their matches are ordered; this search output is not survey order."),
 	results: z.array(searchResultSchema).optional()
 });
 const STOP_WORDS = new Set([
@@ -1335,6 +1548,7 @@ const summarizeForModel = (output) => {
 		}
 	}
 	if (output.nextCursor) lines.push(`More search results are available with cursor ${output.nextCursor}.`);
+	if (output.ordering) lines.push(`Search-result order: ${output.ordering}`);
 	lines.push("Use survey_inspect with action \"item-details\" and itemRef to inspect a result.");
 	return lines.join("\n");
 };
@@ -1370,6 +1584,7 @@ const surveySearchItemsTool = createTool({
 			returned: page.items.length,
 			nextCursor: page.nextCursor,
 			truncated: page.truncated,
+			ordering: "Results are ranked by descending text-match score, then item full key. Matches within each result are ranked by descending score. Neither order is survey or respondent-visible order.",
 			results: page.items
 		};
 	},
@@ -1504,6 +1719,10 @@ const listAssets = (input, snapshot) => {
 		totalAvailable: allAssets.length,
 		returned: assets.length,
 		...nextOffset < allAssets.length ? { nextCursor: String(nextOffset) } : {},
+		listOrdering: {
+			assets: "Alphabetical by assetId; position has no survey meaning.",
+			"assets[].usages": "Deterministic survey translation traversal order; position has no semantic meaning."
+		},
 		assets
 	};
 };
@@ -1695,7 +1914,7 @@ const inputSchema = z.object({
 	alt: z.string().max(2e3).nullable().optional(),
 	continuationMode: z.enum(SURVEY_CHANGE_CONTINUATION_MODES).optional().describe("Required after any earlier mutation candidate in the turn. Use \"append\" to keep earlier candidates, including an imported asset; use \"replace\" only when resubmitting the complete intended proposal."),
 	summary: z.string().min(1).max(500)
-});
+}).strict();
 const slug = (value) => value.toLowerCase().replace(/\.[^.]+$/, "").replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 100) || "image";
 const OMITTED_EMBEDDED_IMAGE_DATA = "[embedded image data omitted from transcript]";
 const getAssetReferenceLabels = (snapshot, assetId) => {
@@ -1876,4 +2095,4 @@ const surveyAssistantTools = Object.freeze({
 //#endregion
 export { surveyAuditTool as i, surveyAssistantTools as n, surveyAssetTool as r, SURVEY_ASSISTANT_TOOL_IDS as t };
 
-//# sourceMappingURL=tools-Hz2p7vyv.mjs.map
+//# sourceMappingURL=tools-DDXaJ8Za.mjs.map