@case-framework/survey-assistant 0.7.0 → 0.9.0

package/README.md

@@ -59,7 +59,6 @@ import {
 import {
   createSurveyAssistantControllerBridge,
   createSurveyAssistantTaskClient,
-  createSurveyAssistantTaskExecutor,
   createSurveyAssistantThreadLauncher,
 } from "@case-framework/survey-assistant/react/integration";
 
@@ -106,6 +105,11 @@ stylesheet has no preflight and scopes generated utilities beneath the panel
 root. A host can pass a partial localization catalog to extend or override the
 defaults without supplying a complete catalog.
 
+Hosts using `/ui` must install `@base-ui/react@^1.8.0` alongside React and
+React DOM. Base UI is an optional peer dependency so server and protocol consumers
+do not need to install it. Use the same Base UI installation for the assistant,
+survey player, editor, and host components.
+
 ```tsx
 <ConnectedSurveyAssistantPanel
   api="/api/survey-assistant/chat"
@@ -215,7 +219,7 @@ export const ratingAssistantCapability = {
     create: "deterministic",
     supportedOperations: [
       "create-item",
-      "update-item-key",
+      "update-response-settings",
       "update-item-translation",
       "patch-item-config",
     ],
@@ -230,6 +234,19 @@ export const ratingAssistantCapability = {
       markdown: "Use min < max and a positive step.",
     },
   ],
+  // Match the host core's declaration; item identity can seed a new scalar slot.
+  normalizeCreate: (item) => ({
+    ...item,
+    config: { responseId: item.id, variableName: "rating", ...item.config },
+  }),
+  deriveResponseSlotDefinitions: (item) => [
+    {
+      slotId: item.config.responseId,
+      variableName: item.config.variableName,
+      valueType: "number",
+      naming: { kind: "variable", path: ["variableName"] },
+    },
+  ],
 } satisfies AssistantItemCapabilityAdapter;
 
 // rating-entry.tsx (client/editor module)
@@ -258,7 +275,8 @@ pnpm benchmark:survey-assistant-operations
 ```
 
 `check` typechecks and builds all entries, copies server references, verifies
-their source and built import graphs, and runs unit tests. `check:release` also
+their source and built import graphs, and runs typed unit/DOM tests plus the real
+SDK streaming integration tests (with a scripted model, no provider requests). `check:release` also
 builds the clean Next host fixture. `benchmark:survey-assistant-operations`
 uses the current built engine output to profile maximum-size typed validation
 and the raw-patch path against a synthetic 5,002-item survey; run `build` first
@@ -266,6 +284,31 @@ when source has changed. The optional Postgres entry accepts a host-owned
 `PostgresStore` or store configuration; it does not read environment variables,
 create hidden singletons, or own connection shutdown.
 
+## Test boundaries
+
+- `test` checks fixtures and runs the Vitest source suite. Its tool-constructor mock
+  deliberately bypasses SDK validation for handler-level negative inputs; the
+  test TypeScript config reflects that mock and keeps schema input/output types.
+  The separate production `typecheck` uses the real SDK types.
+- `test:integration` runs built output through native `node:test` with the real Agent, tools, HTTP handler,
+  stream adapter, transport, and session hook. Only model responses are scripted.
+  Build changed package output first. The editor UI suite also feeds these real
+  streamed candidates through its apply/undo boundary in a separate native ESM
+  process so source-test aliases and mocks cannot replace the SDKs.
+- `test:postgres` also uses native `node:test` and requires
+  `SURVEY_ASSISTANT_TEST_DATABASE_URL`. Use a disposable
+  PostgreSQL database: the test creates a unique schema and drops only that schema
+  in cleanup. It tests isolation, BYTEA roundtrips, deduplication, and concurrent
+  quotas against real PostgreSQL. Missing configuration fails explicitly; this
+  opt-in test is not part of the database-free `check` command.
+- Live model evaluations remain opt-in. DOM tests exercise events but do not
+  establish browser layout, focus, scrolling, or accessibility acceptance.
+
+```sh
+SURVEY_ASSISTANT_TEST_DATABASE_URL=postgresql://localhost/assistant_test \
+  pnpm --filter @case-framework/survey-assistant test:postgres
+```
+
 ## Integration Levels
 
 Use the highest level that fits the host; the lower layers remain available for
@@ -291,3 +334,15 @@ The option does not choose or authorize an identity, and most authenticated
 hosts should omit it unless they want that extra deployment switch. See
 [Real-host integration](./docs/integration.md#optional-experimental-identity-rollout-gate)
 for the exact enablement rules.
+
+### Response-variable authoring (survey schema version 2)
+
+Assistant mutations target exact persistent item IDs. Search exposes resolved editor names and breadcrumbs for discovery; names may repeat. Response-slot declarations from the shared item packages provide persistent IDs, coding names, domains, matrix ownership and computed dependencies. Expressions serialize references as `{slotId, method: "get" | "isDefined"}`.
+
+Use `update-response-settings` with `naming` and `settings` arrays for atomic scalar names, matrix naming components, option export codes and export defaults. Shared core previews validate names, derived families and projected headers; editor application remains a single normal undoable transaction. The built-in registry supports consent, choice and form matrices alongside scalar and embedded forms.
+
+One-shot tasks are `suggest-response-name` (a scalar `itemId` and `slotId`) and `suggest-response-settings` (`slotIds` and a naming category). Response Settings offers selected-variable or filtered-visible-variable suggestions, validates a before/after preview, and applies only on user action. Categories are `fair`, `survey-pattern`, `compact`, and `preferred`. All obey the same naming syntax; FAIR guidance is a project convention, not a certification.
+
+Custom capabilities with conditional components, projected answers or computed behavior need a trusted server-safe `itemCore` constructor shared with the player for complete proposal-time validation. Without it, the assistant cannot inspect those activation dependencies and may propose a change that the editor rejects at apply; no partial change is applied, but the model cannot repair that failure within the original turn. Standard form, choice, consent and matrix items already use shared headless cores.
+
+Slot-only capabilities can use `deriveResponseSlotDefinitions`; creatable custom response capabilities must expose full slot definitions through one of these contracts, including persistent slot IDs, separate variable names, and naming paths and categorical domains where supported. The type-only `deriveResponseSlots` adapter is insufficient for creation under the current schema; it remains an inspection-only adapter. Pass the same capability set to `buildSurveyAssistantTaskContext`, or the editor AI provider/integration's optional `capabilities`, for custom-variable tasks. The server must continue to supply trusted capabilities independently of browser data.

package/dist/{attachments-B0hg3vpT.mjs → attachments-BuNni5vB.mjs}

@@ -8,4 +8,4 @@ const isSurveyAssistantAttachmentMediaType = (mediaType) => SURVEY_ASSISTANT_ATT
 //#endregion
 export { isSurveyAssistantAttachmentMediaType as n, SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES as t };
 
-//# sourceMappingURL=attachments-B0hg3vpT.mjs.map
+//# sourceMappingURL=attachments-BuNni5vB.mjs.map

package/dist/{attachments-B0hg3vpT.mjs.map → attachments-BuNni5vB.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"attachments-B0hg3vpT.mjs","names":[],"sources":["../src/protocol/attachments.ts"],"sourcesContent":["export const SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES = [\n  \"application/pdf\",\n  \"image/png\",\n  \"image/jpeg\",\n] as const;\n\nexport type SurveyAssistantAttachmentMediaType =\n  (typeof SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES)[number];\n\nexport const isSurveyAssistantAttachmentMediaType = (\n  mediaType: string,\n): mediaType is SurveyAssistantAttachmentMediaType =>\n  (SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES as readonly string[]).includes(mediaType.toLowerCase());\n"],"mappings":";AAAA,MAAa,0CAA0C;CACrD;CACA;CACA;CACD;AAKD,MAAa,wCACX,cAEC,wCAA8D,SAAS,UAAU,aAAa,CAAC"}
+{"version":3,"file":"attachments-BuNni5vB.mjs","names":[],"sources":["../src/protocol/attachments.ts"],"sourcesContent":["export const SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES = [\n  \"application/pdf\",\n  \"image/png\",\n  \"image/jpeg\",\n] as const;\n\nexport type SurveyAssistantAttachmentMediaType =\n  (typeof SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES)[number];\n\nexport const isSurveyAssistantAttachmentMediaType = (\n  mediaType: string,\n): mediaType is SurveyAssistantAttachmentMediaType =>\n  (SURVEY_ASSISTANT_ATTACHMENT_MEDIA_TYPES as readonly string[]).includes(mediaType.toLowerCase());\n"],"mappings":";AAAA,MAAa,0CAA0C;CACrD;CACA;CACA;AACF;AAKA,MAAa,wCACX,cAEC,wCAA8D,SAAS,UAAU,YAAY,CAAC"}

package/dist/{authoring-references-BJQ_1nMX.mjs → authoring-references-CmwLc_C8.mjs}

@@ -1,7 +1,7 @@
 import path, { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";
-//#region ../../node_modules/.pnpm/tsdown@0.21.10_synckit@0.11.13_typescript@6.0.3/node_modules/tsdown/esm-shims.js
+//#region ../../node_modules/.pnpm/tsdown@0.23.0_@volar+typescript@2.4.28_typescript@6.0.3__typescript@6.0.3_unrun@0.2.39/node_modules/tsdown/esm-shims.js
 const getFilename = () => fileURLToPath(import.meta.url);
 const getDirname = () => path.dirname(getFilename());
 const __dirname = /* @__PURE__ */ getDirname();
@@ -11,29 +11,38 @@ const loadReference = (fileName) => readFileSync(resolve(__dirname, "references"
 const surveyAuthoringReferenceTopics = [
 	"core-rules",
 	"survey-data-model",
+	"response-variables",
 	"source-material-surveys",
 	"localization",
 	"rich-text-content",
-	"item-types",
-	"embedded-forms",
+	"element-types",
+	"follow-ups",
 	"expressions",
 	"assistant-operations",
 	"fair-by-design",
 	"survey-quality"
 ];
-const ITEM_TYPE_SECTION_HEADINGS = {
-	group: "group",
-	"page-break": "page-break",
-	infoItem: "infoItem",
-	choiceItem: "choiceItem",
-	formItem: "formItem"
+const ELEMENT_TYPE_SECTION_HEADINGS = {
+	information: "information",
+	text: "text",
+	number: "number",
+	date: "date",
+	boolean: "boolean",
+	choice: "choice",
+	consent: "consent",
+	choiceMatrix: "choiceMatrix",
+	formMatrix: "formMatrix"
 };
-const builtInSurveyAuthoringItemTypes = Object.freeze(Object.keys(ITEM_TYPE_SECTION_HEADINGS));
-const extractLevelTwoSection = (markdown, heading) => {
+const builtInSurveyAuthoringElementTypes = Object.freeze(Object.keys(ELEMENT_TYPE_SECTION_HEADINGS));
+const extractSection = (markdown, heading, level = 2) => {
 	const lines = markdown.split("\n");
-	const sectionStart = lines.findIndex((line) => line.trim() === `## ${heading}`);
+	const prefix = "#".repeat(level);
+	const sectionStart = lines.findIndex((line) => line.trim() === `${prefix} ${heading}`);
 	if (sectionStart < 0) return;
-	const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => line.startsWith("## "));
+	const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => {
+		const match = /^(#+) /.exec(line);
+		return match !== null && match[1].length <= level;
+	});
 	const sectionEnd = nextSectionOffset < 0 ? lines.length : sectionStart + 1 + nextSectionOffset;
 	return lines.slice(sectionStart, sectionEnd).join("\n").trim();
 };
@@ -43,6 +52,11 @@ const surveyAuthoringReferences = {
 		content: loadReference("core-rules.md"),
 		loadWhen: "Load when the task depends on canonical tool choice, validation/apply semantics, identifier handling, or another cross-cutting authoring rule that the current turn has not already established."
 	},
+	"response-variables": {
+		title: "Response variables and coding",
+		content: loadReference("response-variables.md"),
+		loadWhen: "Load before creating response inputs, changing variable names, option codes, matrix coding components, or export settings. Inspect current response slots for exact IDs and domains."
+	},
 	"survey-data-model": {
 		title: "Survey data model",
 		content: loadReference("survey-data-model.md"),
@@ -63,15 +77,15 @@ const surveyAuthoringReferences = {
 		content: loadReference("rich-text-content.md"),
 		loadWhen: "Load before authoring or changing meaningful formatting, links, images, headings, lists, info boxes, separators, footnotes, or existing structured rich-text content; do not load it for ordinary unformatted plain text."
 	},
-	"item-types": {
-		title: "Item types",
-		content: loadReference("item-types.md"),
-		loadWhen: "Load with itemType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit itemType only for a genuine cross-type comparison."
+	"element-types": {
+		title: "Element types",
+		content: loadReference("element-types.md"),
+		loadWhen: "Load with elementType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit elementType only for a genuine cross-type comparison."
 	},
-	"embedded-forms": {
-		title: "Choice option embedded forms",
-		content: loadReference("embedded-forms.md"),
-		loadWhen: "Load before creating or changing a choice-option follow-up or embedded form, including \"Other, specify\", option-specific inputs, embedded field groups, or embedded-form layout and translations."
+	"follow-ups": {
+		title: "Option-inline follow-ups",
+		content: loadReference("follow-ups.md"),
+		loadWhen: "Load before creating or changing a choice-option follow-up, including \"Other, specify\", option-specific inputs, semantic sections, layout and owner-role translations."
 	},
 	expressions: {
 		title: "Expressions",
@@ -81,7 +95,7 @@ const surveyAuthoringReferences = {
 	"assistant-operations": {
 		title: "Assistant operations",
 		content: loadReference("assistant-operations.md"),
-		loadWhen: "Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add itemType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging."
+		loadWhen: "Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add elementType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging."
 	},
 	"fair-by-design": {
 		title: "FAIR-by-design survey authoring",
@@ -97,19 +111,22 @@ const surveyAuthoringReferences = {
 const formatSurveyAuthoringReferenceRoutingInstructions = () => [
 	"Authoring-reference routing rules:",
 	"Load a relevant focused reference before the first affected mutation or substantive advice, not after guessing a payload or learning through validator failures. Do not reload a reference when its exact relevant contract is already present in the current turn. References define stable authoring conventions and payload grammar; current survey state and currently available runtime references still come from inspection and context tools.",
-	"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with itemType before changing unfamiliar capability configuration or behavior.",
+	"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with elementType before changing unfamiliar capability configuration or behavior.",
 	...surveyAuthoringReferenceTopics.map((topic) => `- ${topic}: ${surveyAuthoringReferences[topic].loadWhen}`)
 ].join("\n");
-const getBuiltInItemTypeAuthoringReference = (itemType) => {
-	const heading = ITEM_TYPE_SECTION_HEADINGS[itemType];
+const getBuiltInElementTypeAuthoringReference = (elementType) => {
+	const heading = ELEMENT_TYPE_SECTION_HEADINGS[elementType];
 	if (!heading) return;
-	const content = extractLevelTwoSection(surveyAuthoringReferences["item-types"].content, heading);
-	return content ? {
-		title: `${heading} item type`,
-		content
-	} : void 0;
+	const content = extractSection(surveyAuthoringReferences["element-types"].content, heading);
+	if (!content) return void 0;
+	const exampleHeading = elementType === "choice" ? "Full worked example: a single-choice question" : elementType === "text" || elementType === "number" ? "Full worked example: a composed question with two inputs" : void 0;
+	const example = exampleHeading ? extractSection(surveyAuthoringReferences["assistant-operations"].content, exampleHeading, 3) : void 0;
+	return {
+		title: `${heading} element type`,
+		content: example ? `${content}\n\n${example}` : content
+	};
 };
 //#endregion
-export { surveyAuthoringReferences as a, surveyAuthoringReferenceTopics as i, formatSurveyAuthoringReferenceRoutingInstructions as n, getBuiltInItemTypeAuthoringReference as r, builtInSurveyAuthoringItemTypes as t };
+export { surveyAuthoringReferences as a, surveyAuthoringReferenceTopics as i, formatSurveyAuthoringReferenceRoutingInstructions as n, getBuiltInElementTypeAuthoringReference as r, builtInSurveyAuthoringElementTypes as t };
 
-//# sourceMappingURL=authoring-references-BJQ_1nMX.mjs.map
+//# sourceMappingURL=authoring-references-CmwLc_C8.mjs.map

package/dist/authoring-references-CmwLc_C8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-references-CmwLc_C8.mjs","names":[],"sources":["../../../node_modules/.pnpm/tsdown@0.23.0_@volar+typescript@2.4.28_typescript@6.0.3__typescript@6.0.3_unrun@0.2.39/node_modules/tsdown/esm-shims.js","../src/server/authoring-references.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n","import { readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\n\nconst loadReference = (fileName: string) =>\n  readFileSync(resolve(__dirname, \"references\", fileName), \"utf8\").trim();\n\nexport const surveyAuthoringReferenceTopics = [\n  \"core-rules\",\n  \"survey-data-model\",\n  \"response-variables\",\n  \"source-material-surveys\",\n  \"localization\",\n  \"rich-text-content\",\n  \"element-types\",\n  \"follow-ups\",\n  \"expressions\",\n  \"assistant-operations\",\n  \"fair-by-design\",\n  \"survey-quality\",\n] as const;\n\nexport type SurveyAuthoringReferenceTopic = (typeof surveyAuthoringReferenceTopics)[number];\n\ntype SurveyAuthoringReferenceEntry = {\n  title: string;\n  content: string;\n  loadWhen: string;\n};\n\nconst ELEMENT_TYPE_SECTION_HEADINGS: Readonly<Record<string, string>> = {\n  information: \"information\",\n  text: \"text\",\n  number: \"number\",\n  date: \"date\",\n  boolean: \"boolean\",\n  choice: \"choice\",\n  consent: \"consent\",\n  choiceMatrix: \"choiceMatrix\",\n  formMatrix: \"formMatrix\",\n};\n\nexport const builtInSurveyAuthoringElementTypes = Object.freeze(\n  Object.keys(ELEMENT_TYPE_SECTION_HEADINGS),\n);\n\nconst extractSection = (markdown: string, heading: string, level = 2): string | undefined => {\n  const lines = markdown.split(\"\\n\");\n  const prefix = \"#\".repeat(level);\n  const sectionStart = lines.findIndex((line) => line.trim() === `${prefix} ${heading}`);\n  if (sectionStart < 0) {\n    return undefined;\n  }\n\n  const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => {\n    const match = /^(#+) /.exec(line);\n    return match !== null && match[1].length <= level;\n  });\n  const sectionEnd = nextSectionOffset < 0 ? lines.length : sectionStart + 1 + nextSectionOffset;\n\n  return lines.slice(sectionStart, sectionEnd).join(\"\\n\").trim();\n};\n\nexport const surveyAuthoringReferences = {\n  \"core-rules\": {\n    title: \"Core authoring rules\",\n    content: loadReference(\"core-rules.md\"),\n    loadWhen:\n      \"Load when the task depends on canonical tool choice, validation/apply semantics, identifier handling, or another cross-cutting authoring rule that the current turn has not already established.\",\n  },\n  \"response-variables\": {\n    title: \"Response variables and coding\",\n    content: loadReference(\"response-variables.md\"),\n    loadWhen:\n      \"Load before creating response inputs, changing variable names, option codes, matrix coding components, or export settings. Inspect current response slots for exact IDs and domains.\",\n  },\n  \"survey-data-model\": {\n    title: \"Survey data model\",\n    content: loadReference(\"survey-data-model.md\"),\n    loadWhen:\n      \"Load before reasoning about raw survey storage, hierarchy, ids, translation maps, assets, template values, or any direct survey-json-patch path whose exact location has not already been inspected and documented in the current turn.\",\n  },\n  \"source-material-surveys\": {\n    title: \"Source-material survey implementation\",\n    content: loadReference(\"source-material-surveys.md\"),\n    loadWhen:\n      \"Load before implementing or adapting a questionnaire, document, image, or other supplied source material so completeness, respondent-input mapping, meaningful layout, language, and digital adaptation rules are available before the first mutation.\",\n  },\n  localization: {\n    title: \"Survey localization\",\n    content: loadReference(\"localization.md\"),\n    loadWhen:\n      \"Load before adding, removing, translating, or assessing a survey locale, including requests for localization completeness or locale lifecycle changes.\",\n  },\n  \"rich-text-content\": {\n    title: \"Rich text content\",\n    content: loadReference(\"rich-text-content.md\"),\n    loadWhen:\n      \"Load before authoring or changing meaningful formatting, links, images, headings, lists, info boxes, separators, footnotes, or existing structured rich-text content; do not load it for ordinary unformatted plain text.\",\n  },\n  \"element-types\": {\n    title: \"Element types\",\n    content: loadReference(\"element-types.md\"),\n    loadWhen:\n      \"Load with elementType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit elementType only for a genuine cross-type comparison.\",\n  },\n  \"follow-ups\": {\n    title: \"Option-inline follow-ups\",\n    content: loadReference(\"follow-ups.md\"),\n    loadWhen:\n      'Load before creating or changing a choice-option follow-up, including \"Other, specify\", option-specific inputs, semantic sections, layout and owner-role translations.',\n  },\n  expressions: {\n    title: \"Expressions\",\n    content: loadReference(\"expressions.md\"),\n    loadWhen:\n      \"Load before the first survey_expression prepare call for expression, condition, validation-expression, prefill, or template-value work unless the exact relevant JsonExpression and mutation shapes were already supplied by a current-turn authoring reference. survey_expression context supplies currently available runtime references and value types, but it does not replace the grammar reference. Expressions are not assumed to be survey-response-only; use the references and variable sources supported by the current runtime and reference.\",\n  },\n  \"assistant-operations\": {\n    title: \"Assistant operations\",\n    content: loadReference(\"assistant-operations.md\"),\n    loadWhen:\n      \"Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add elementType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging.\",\n  },\n  \"fair-by-design\": {\n    title: \"FAIR-by-design survey authoring\",\n    content: loadReference(\"fair-by-design.md\"),\n    loadWhen:\n      \"Load before advising or editing when FAIR, interoperability, harmonization, cross-study reuse, stable coding, value sets, missingness semantics, metadata, provenance, versioning, standard instruments, controlled vocabularies, or machine-readable export is material; do not impose it on ordinary authoring.\",\n  },\n  \"survey-quality\": {\n    title: \"Survey quality review\",\n    content: loadReference(\"survey-quality.md\"),\n    loadWhen:\n      \"Load before a substantive questionnaire-quality critique, wording or flow review, respondent-burden assessment, or recommendations about measurement quality; it is not required for a purely technical defect check.\",\n  },\n} as const satisfies Record<SurveyAuthoringReferenceTopic, SurveyAuthoringReferenceEntry>;\n\nexport const formatSurveyAuthoringReferenceRoutingInstructions = (): string =>\n  [\n    \"Authoring-reference routing rules:\",\n    \"Load a relevant focused reference before the first affected mutation or substantive advice, not after guessing a payload or learning through validator failures. Do not reload a reference when its exact relevant contract is already present in the current turn. References define stable authoring conventions and payload grammar; current survey state and currently available runtime references still come from inspection and context tools.\",\n    \"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with elementType before changing unfamiliar capability configuration or behavior.\",\n    ...surveyAuthoringReferenceTopics.map(\n      (topic) => `- ${topic}: ${surveyAuthoringReferences[topic].loadWhen}`,\n    ),\n  ].join(\"\\n\");\n\nexport const getBuiltInElementTypeAuthoringReference = (\n  elementType: string,\n): { title: string; content: string } | undefined => {\n  const heading = ELEMENT_TYPE_SECTION_HEADINGS[elementType];\n  if (!heading) {\n    return undefined;\n  }\n\n  const content = extractSection(surveyAuthoringReferences[\"element-types\"].content, heading);\n  if (!content) return undefined;\n  // Keep executable examples in one source while retaining them in focused lookups.\n  // Most authoring turns deliberately never load the full operations catalog.\n  const exampleHeading =\n    elementType === \"choice\"\n      ? \"Full worked example: a single-choice question\"\n      : elementType === \"text\" || elementType === \"number\"\n        ? \"Full worked example: a composed question with two inputs\"\n        : undefined;\n  const example = exampleHeading\n    ? extractSection(surveyAuthoringReferences[\"assistant-operations\"].content, exampleHeading, 3)\n    : undefined;\n  return {\n    title: `${heading} element type`,\n    content: example ? `${content}\\n\\n${example}` : content,\n  };\n};\n"],"x_google_ignoreList":[0],"mappings":"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"}