@case-framework/survey-assistant 0.7.0 → 0.8.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-DbuOKerg.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,6 +11,7 @@ const loadReference = (fileName) => readFileSync(resolve(__dirname, "references"
 const surveyAuthoringReferenceTopics = [
 	"core-rules",
 	"survey-data-model",
+	"response-variables",
 	"source-material-surveys",
 	"localization",
 	"rich-text-content",
@@ -25,8 +26,11 @@ const ITEM_TYPE_SECTION_HEADINGS = {
 	group: "group",
 	"page-break": "page-break",
 	infoItem: "infoItem",
+	consentItem: "consentItem",
 	choiceItem: "choiceItem",
-	formItem: "formItem"
+	formItem: "formItem",
+	choiceMatrix: "choiceMatrix",
+	formMatrix: "formMatrix"
 };
 const builtInSurveyAuthoringItemTypes = Object.freeze(Object.keys(ITEM_TYPE_SECTION_HEADINGS));
 const extractLevelTwoSection = (markdown, heading) => {
@@ -43,6 +47,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"),
@@ -112,4 +121,4 @@ const getBuiltInItemTypeAuthoringReference = (itemType) => {
 //#endregion
 export { surveyAuthoringReferences as a, surveyAuthoringReferenceTopics as i, formatSurveyAuthoringReferenceRoutingInstructions as n, getBuiltInItemTypeAuthoringReference as r, builtInSurveyAuthoringItemTypes as t };
 
-//# sourceMappingURL=authoring-references-BJQ_1nMX.mjs.map
+//# sourceMappingURL=authoring-references-DbuOKerg.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-references-DbuOKerg.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  \"item-types\",\n  \"embedded-forms\",\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 ITEM_TYPE_SECTION_HEADINGS: Readonly<Record<string, string>> = {\n  group: \"group\",\n  \"page-break\": \"page-break\",\n  infoItem: \"infoItem\",\n  consentItem: \"consentItem\",\n  choiceItem: \"choiceItem\",\n  formItem: \"formItem\",\n  choiceMatrix: \"choiceMatrix\",\n  formMatrix: \"formMatrix\",\n};\n\nexport const builtInSurveyAuthoringItemTypes = Object.freeze(\n  Object.keys(ITEM_TYPE_SECTION_HEADINGS),\n);\n\nconst extractLevelTwoSection = (markdown: string, heading: string): string | undefined => {\n  const lines = markdown.split(\"\\n\");\n  const sectionStart = lines.findIndex((line) => line.trim() === `## ${heading}`);\n  if (sectionStart < 0) {\n    return undefined;\n  }\n\n  const nextSectionOffset = lines\n    .slice(sectionStart + 1)\n    .findIndex((line) => line.startsWith(\"## \"));\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  \"item-types\": {\n    title: \"Item types\",\n    content: loadReference(\"item-types.md\"),\n    loadWhen:\n      \"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.\",\n  },\n  \"embedded-forms\": {\n    title: \"Choice option embedded forms\",\n    content: loadReference(\"embedded-forms.md\"),\n    loadWhen:\n      '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.',\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 itemType 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 itemType before changing unfamiliar capability configuration or behavior.\",\n    ...surveyAuthoringReferenceTopics.map(\n      (topic) => `- ${topic}: ${surveyAuthoringReferences[topic].loadWhen}`,\n    ),\n  ].join(\"\\n\");\n\nexport const getBuiltInItemTypeAuthoringReference = (\n  itemType: string,\n): { title: string; content: string } | undefined => {\n  const heading = ITEM_TYPE_SECTION_HEADINGS[itemType];\n  if (!heading) {\n    return undefined;\n  }\n\n  const content = extractLevelTwoSection(surveyAuthoringReferences[\"item-types\"].content, heading);\n  return content ? { title: `${heading} item type`, content } : undefined;\n};\n"],"x_google_ignoreList":[0],"mappings":";;;;AAIA,MAAM,oBAAoB,cAAc,YAAY,GAAG;AACvD,MAAM,mBAAmB,KAAK,QAAQ,YAAY,CAAC;AAEnD,MAAa,YAA4B,2BAAW;;;ACJpD,MAAM,iBAAiB,aACrB,aAAa,QAAQ,WAAW,cAAc,QAAQ,GAAG,MAAM,CAAC,CAAC,KAAK;AAExE,MAAa,iCAAiC;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAUA,MAAM,6BAA+D;CACnE,OAAO;CACP,cAAc;CACd,UAAU;CACV,aAAa;CACb,YAAY;CACZ,UAAU;CACV,cAAc;CACd,YAAY;AACd;AAEA,MAAa,kCAAkC,OAAO,OACpD,OAAO,KAAK,0BAA0B,CACxC;AAEA,MAAM,0BAA0B,UAAkB,YAAwC;CACxF,MAAM,QAAQ,SAAS,MAAM,IAAI;CACjC,MAAM,eAAe,MAAM,WAAW,SAAS,KAAK,KAAK,MAAM,MAAM,SAAS;CAC9E,IAAI,eAAe,GACjB;CAGF,MAAM,oBAAoB,MACvB,MAAM,eAAe,CAAC,CAAC,CACvB,WAAW,SAAS,KAAK,WAAW,KAAK,CAAC;CAC7C,MAAM,aAAa,oBAAoB,IAAI,MAAM,SAAS,eAAe,IAAI;CAE7E,OAAO,MAAM,MAAM,cAAc,UAAU,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK;AAC/D;AAEA,MAAa,4BAA4B;CACvC,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,eAAe;EACtC,UACE;CACJ;CACA,sBAAsB;EACpB,OAAO;EACP,SAAS,cAAc,uBAAuB;EAC9C,UACE;CACJ;CACA,qBAAqB;EACnB,OAAO;EACP,SAAS,cAAc,sBAAsB;EAC7C,UACE;CACJ;CACA,2BAA2B;EACzB,OAAO;EACP,SAAS,cAAc,4BAA4B;EACnD,UACE;CACJ;CACA,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,iBAAiB;EACxC,UACE;CACJ;CACA,qBAAqB;EACnB,OAAO;EACP,SAAS,cAAc,sBAAsB;EAC7C,UACE;CACJ;CACA,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,eAAe;EACtC,UACE;CACJ;CACA,kBAAkB;EAChB,OAAO;EACP,SAAS,cAAc,mBAAmB;EAC1C,UACE;CACJ;CACA,aAAa;EACX,OAAO;EACP,SAAS,cAAc,gBAAgB;EACvC,UACE;CACJ;CACA,wBAAwB;EACtB,OAAO;EACP,SAAS,cAAc,yBAAyB;EAChD,UACE;CACJ;CACA,kBAAkB;EAChB,OAAO;EACP,SAAS,cAAc,mBAAmB;EAC1C,UACE;CACJ;CACA,kBAAkB;EAChB,OAAO;EACP,SAAS,cAAc,mBAAmB;EAC1C,UACE;CACJ;AACF;AAEA,MAAa,0DACX;CACE;CACA;CACA;CACA,GAAG,+BAA+B,KAC/B,UAAU,KAAK,MAAM,IAAI,0BAA0B,MAAM,CAAC,UAC7D;AACF,CAAC,CAAC,KAAK,IAAI;AAEb,MAAa,wCACX,aACmD;CACnD,MAAM,UAAU,2BAA2B;CAC3C,IAAI,CAAC,SACH;CAGF,MAAM,UAAU,uBAAuB,0BAA0B,aAAa,CAAC,SAAS,OAAO;CAC/F,OAAO,UAAU;EAAE,OAAO,GAAG,QAAQ;EAAa;CAAQ,IAAI,KAAA;AAChE"}

package/dist/{capabilities-DVTfogjv.d.mts → capabilities-CmeeAjEc.d.mts}

@@ -1,5 +1,4 @@
 import { z } from "zod";
-
 //#region src/protocol/capabilities.d.ts
 declare const assistantItemCreateModeSchema: z.ZodEnum<{
   deterministic: "deterministic";
@@ -43,8 +42,8 @@ declare const assistantItemTypeManifestSchema: z.ZodObject<{
     unsupported: "unsupported";
   }>;
   supportedOperations: z.ZodArray<z.ZodEnum<{
+    "update-response-settings": "update-response-settings";
     "create-item": "create-item";
-    "update-item-key": "update-item-key";
     "update-item-label": "update-item-label";
     "update-item-color": "update-item-color";
     "update-item-translation": "update-item-translation";
@@ -119,8 +118,8 @@ declare const surveyAssistantCapabilityManifestSchema: z.ZodObject<{
       unsupported: "unsupported";
     }>;
     supportedOperations: z.ZodArray<z.ZodEnum<{
+      "update-response-settings": "update-response-settings";
       "create-item": "create-item";
-      "update-item-key": "update-item-key";
       "update-item-label": "update-item-label";
       "update-item-color": "update-item-color";
       "update-item-translation": "update-item-translation";
@@ -190,4 +189,4 @@ type AssistantItemTypeManifest = z.infer<typeof assistantItemTypeManifestSchema>
 type SurveyAssistantCapabilityManifest = z.infer<typeof surveyAssistantCapabilityManifestSchema>;
 //#endregion
 export { AssistantResponseSlot as a, assistantItemAuthoringSchema as c, assistantResponseSlotSchema as d, surveyAssistantCapabilityManifestSchema as f, AssistantItemTypeManifest as i, assistantItemCreateModeSchema as l, AssistantItemAuthoring as n, SurveyAssistantCapabilityManifest as o, AssistantItemCreateMode as r, assistantContentSurfaceSchema as s, AssistantContentSurface as t, assistantItemTypeManifestSchema as u };
-//# sourceMappingURL=capabilities-DVTfogjv.d.mts.map
+//# sourceMappingURL=capabilities-CmeeAjEc.d.mts.map

package/dist/capabilities-CmeeAjEc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-CmeeAjEc.d.mts","names":[],"sources":["../src/protocol/capabilities.ts"],"mappings":";;cAGa,+BAA6B,EAAA;;;;;cAM7B,+BAA6B,EAAA;;;;;;;;;;;;;;;;GAOxC,EAAA,KAAA;cAEW,6BAA2B,EAAA;;;GAGtC,EAAA,KAAA;cAEW,8BAA4B,EAAA;;;GAGvC,EAAA,KAAA;cAMW,iCAA+B,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAa1C,EAAA,KAAA;cAEW,yCAAuC,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAGlD,EAAA,KAAA;KAEU,0BAA0B,EAAE,aAAa;KACzC,0BAA0B,EAAE,aAAa;KACzC,wBAAwB,EAAE,aAAa;KACvC,yBAAyB,EAAE,aAAa;KAExC,4BAA4B,EAAE,aAAa;KAC3C,oCAAoC,EAAE,aACzC"}

package/dist/{capabilities-1KNnNO1_.mjs → capabilities-DCMA71PP.mjs}

@@ -1,4 +1,4 @@
-import { q as assistantItemTypeManifestSchema } from "./protocol-BhzQbx81.mjs";
+import { Y as assistantItemTypeManifestSchema } from "./protocol-CF4Bh_Ch.mjs";
 import { buildCapabilityDigest, stableStringify } from "./digest.mjs";
 //#region src/engine/capabilities.ts
 const resolveAssistantCapabilityReference = ({ capabilities, itemType, topic }) => capabilities?.byItemType.get(itemType)?.references?.find((reference) => reference.topic === topic);
@@ -11,6 +11,7 @@ const createSurveyAssistantCapabilities = (capabilities) => {
 		const itemType = manifest.itemType;
 		if (byItemType.has(itemType)) throw new Error(`Duplicate survey assistant capability for item type "${itemType}".`);
 		if (manifest.create === "deterministic" && !manifest.supportedOperations.includes("create-item")) throw new Error(`Deterministically creatable item type "${itemType}" must support "create-item".`);
+		if (manifest.create === "deterministic" && capability.deriveResponseSlots && !capability.deriveResponseSlotDefinitions && !capability.itemCore) throw new Error(`Creatable response item type "${itemType}" must supply deriveResponseSlotDefinitions with persistent slot IDs and separate variable names. Type-only deriveResponseSlots cannot define current response coding.`);
 		const declaredReferenceTopics = new Set(manifest.referenceTopics ?? []);
 		for (const reference of capability.references ?? []) if (!declaredReferenceTopics.has(reference.topic)) throw new Error(`Capability reference "${reference.topic}" for item type "${itemType}" is missing from manifest.referenceTopics.`);
 		byItemType.set(itemType, capability);
@@ -26,22 +27,6 @@ const createSurveyAssistantCapabilities = (capabilities) => {
 	};
 };
 const getDeterministicCreateItemTypes = (manifest) => manifest.itemTypes.filter((entry) => entry.create === "deterministic").map((entry) => entry.itemType);
-const resolveAssistantItemCreation = ({ itemType, manifest, parentItemId }) => {
-	const capability = manifest.itemTypes.find((entry) => entry.itemType === itemType);
-	if (capability?.create === "deterministic") return { kind: "deterministic" };
-	if (capability?.create === "interactive-only") return {
-		kind: "ui-intent",
-		intent: {
-			kind: "open-create-item",
-			itemType,
-			parentItemId
-		}
-	};
-	return {
-		kind: "unsupported",
-		reason: capability ? `Item type "${itemType}" does not support assistant creation.` : `Item type "${itemType}" is not installed.`
-	};
-};
 const createUnsupportedItemCapability = ({ displayName, itemType }) => ({ manifest: {
 	itemType,
 	capabilityVersion: "unsupported-v1",
@@ -68,6 +53,6 @@ const assertSurveyAssistantCapabilities = ({ manifest, trustedCapabilities, vers
 	}
 };
 //#endregion
-export { getDeterministicCreateItemTypes as a, resolveAssistantItemCreation as c, createUnsupportedItemCapability as i, assertSurveyAssistantCapabilities as n, inspectAssistantItem as o, createSurveyAssistantCapabilities as r, resolveAssistantCapabilityReference as s, SurveyAssistantCapabilityMismatchError as t };
+export { getDeterministicCreateItemTypes as a, createUnsupportedItemCapability as i, assertSurveyAssistantCapabilities as n, inspectAssistantItem as o, createSurveyAssistantCapabilities as r, resolveAssistantCapabilityReference as s, SurveyAssistantCapabilityMismatchError as t };
 
-//# sourceMappingURL=capabilities-1KNnNO1_.mjs.map
+//# sourceMappingURL=capabilities-DCMA71PP.mjs.map

package/dist/capabilities-DCMA71PP.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-DCMA71PP.mjs","names":[],"sources":["../src/engine/capabilities.ts"],"sourcesContent":["import type { z } from \"zod\";\nimport type {\n  ItemTypeRegistry,\n  RawSurveyItem,\n  ResponseSlotDefinition,\n  ValueType,\n} from \"@case-framework/survey-core\";\nimport type {\n  AssistantItemTypeManifest,\n  JsonValue,\n  SurveyAssistantCapabilityManifest,\n  SurveyOperation,\n  SurveyValidationIssue,\n} from \"../protocol\";\nimport { assistantItemTypeManifestSchema } from \"../protocol\";\nimport { buildCapabilityDigest, stableStringify } from \"../protocol/digest\";\n\nexport interface AssistantCapabilityReference {\n  topic: string;\n  title?: string;\n  markdown: string;\n}\n\nexport interface AssistantItemInspection {\n  summary: string;\n  details?: JsonValue;\n}\n\nexport interface AssistantItemCapabilityAdapter {\n  manifest: AssistantItemTypeManifest;\n  /** Trusted server-safe core shared with the player, including response activation dependencies. */\n  itemCore?: ItemTypeRegistry[string];\n  references?: AssistantCapabilityReference[];\n  configurationSchema?: z.ZodType;\n  materializePreset?: (\n    presetId: string,\n    locale: string,\n  ) => {\n    config: RawSurveyItem[\"config\"];\n    translations: NonNullable<Extract<SurveyOperation, { kind: \"create-item\" }>[\"translations\"]>;\n  };\n  validContentKeys?: (item: RawSurveyItem) => string[];\n  normalizeCreate?: (item: RawSurveyItem) => RawSurveyItem;\n  requiredCreateContentKeys?: (item: RawSurveyItem) => string[];\n  validateItem?: (item: RawSurveyItem) => SurveyValidationIssue[];\n  supportsOperation?: (operation: SurveyOperation) => boolean;\n  deriveResponseSlotDefinitions?: (item: RawSurveyItem) => ResponseSlotDefinition[];\n  /** Type-only inspection adapter. Creatable response items require full definitions. */\n  deriveResponseSlots?: (item: RawSurveyItem) => Record<string, ValueType>;\n  inspectItem?: (item: RawSurveyItem) => AssistantItemInspection;\n}\n\nexport interface SurveyAssistantCapabilitySet {\n  manifest: SurveyAssistantCapabilityManifest;\n  byItemType: ReadonlyMap<string, AssistantItemCapabilityAdapter>;\n}\n\nexport const resolveAssistantCapabilityReference = ({\n  capabilities,\n  itemType,\n  topic,\n}: {\n  capabilities: SurveyAssistantCapabilitySet | undefined;\n  itemType: string;\n  topic: string;\n}): AssistantCapabilityReference | undefined =>\n  capabilities?.byItemType\n    .get(itemType)\n    ?.references?.find((reference) => reference.topic === topic);\n\nexport const inspectAssistantItem = ({\n  capabilities,\n  item,\n}: {\n  capabilities: SurveyAssistantCapabilitySet | undefined;\n  item: RawSurveyItem;\n}): AssistantItemInspection | undefined =>\n  capabilities?.byItemType.get(item.itemType)?.inspectItem?.(item);\n\nexport const createSurveyAssistantCapabilities = (\n  capabilities: readonly AssistantItemCapabilityAdapter[],\n): SurveyAssistantCapabilitySet => {\n  const byItemType = new Map<string, AssistantItemCapabilityAdapter>();\n  const normalizedManifests: AssistantItemTypeManifest[] = [];\n\n  for (const capability of capabilities) {\n    const manifest = assistantItemTypeManifestSchema.parse(capability.manifest);\n    const itemType = manifest.itemType;\n    if (byItemType.has(itemType)) {\n      throw new Error(`Duplicate survey assistant capability for item type \"${itemType}\".`);\n    }\n    if (\n      manifest.create === \"deterministic\" &&\n      !manifest.supportedOperations.includes(\"create-item\")\n    ) {\n      throw new Error(\n        `Deterministically creatable item type \"${itemType}\" must support \"create-item\".`,\n      );\n    }\n    if (\n      manifest.create === \"deterministic\" &&\n      capability.deriveResponseSlots &&\n      !capability.deriveResponseSlotDefinitions &&\n      !capability.itemCore\n    ) {\n      throw new Error(\n        `Creatable response item type \"${itemType}\" must supply deriveResponseSlotDefinitions with persistent slot IDs and separate variable names. Type-only deriveResponseSlots cannot define current response coding.`,\n      );\n    }\n    const declaredReferenceTopics = new Set(manifest.referenceTopics ?? []);\n    for (const reference of capability.references ?? []) {\n      if (!declaredReferenceTopics.has(reference.topic)) {\n        throw new Error(\n          `Capability reference \"${reference.topic}\" for item type \"${itemType}\" is missing from manifest.referenceTopics.`,\n        );\n      }\n    }\n    byItemType.set(itemType, capability);\n    normalizedManifests.push(\n      assistantItemTypeManifestSchema.parse(JSON.parse(JSON.stringify(manifest))),\n    );\n  }\n\n  const itemTypes = normalizedManifests.sort((left, right) =>\n    left.itemType.localeCompare(right.itemType),\n  );\n  const manifestWithoutDigest = { itemTypes };\n\n  return {\n    manifest: {\n      ...manifestWithoutDigest,\n      digest: buildCapabilityDigest(manifestWithoutDigest),\n    },\n    byItemType,\n  };\n};\n\nexport const getDeterministicCreateItemTypes = (\n  manifest: SurveyAssistantCapabilityManifest,\n): string[] =>\n  manifest.itemTypes\n    .filter((entry) => entry.create === \"deterministic\")\n    .map((entry) => entry.itemType);\n\nexport const createUnsupportedItemCapability = ({\n  displayName,\n  itemType,\n}: {\n  displayName: string;\n  itemType: string;\n}): AssistantItemCapabilityAdapter => ({\n  manifest: {\n    itemType,\n    capabilityVersion: \"unsupported-v1\",\n    displayName,\n    create: \"unsupported\",\n    supportedOperations: [],\n    contentSurfaces: [],\n  },\n});\n\nexport class SurveyAssistantCapabilityMismatchError extends Error {\n  readonly code = \"survey-assistant-capability-mismatch\";\n\n  constructor(message = \"Survey assistant capabilities changed; start a fresh turn and retry.\") {\n    super(message);\n    this.name = \"SurveyAssistantCapabilityMismatchError\";\n  }\n}\n\nexport const assertSurveyAssistantCapabilities = ({\n  manifest,\n  trustedCapabilities,\n  versionDigest,\n}: {\n  manifest: SurveyAssistantCapabilityManifest;\n  trustedCapabilities?: SurveyAssistantCapabilitySet;\n  versionDigest: string;\n}): void => {\n  const { digest: claimedDigest, ...manifestWithoutDigest } = manifest;\n  const computedDigest = buildCapabilityDigest(manifestWithoutDigest);\n  if (claimedDigest !== computedDigest || versionDigest !== claimedDigest) {\n    throw new SurveyAssistantCapabilityMismatchError();\n  }\n\n  if (trustedCapabilities) {\n    const withoutContextualPresets = ({\n      creationPresets: _creationPresets,\n      ...capability\n    }: AssistantItemTypeManifest): Omit<AssistantItemTypeManifest, \"creationPresets\"> => capability;\n    const claimedBaseCapabilities = manifest.itemTypes.map(withoutContextualPresets);\n    const trustedBaseCapabilities =\n      trustedCapabilities.manifest.itemTypes.map(withoutContextualPresets);\n\n    // Creation presets are editor-registry context for the model. They do not\n    // grant operations or install executable adapters, so the server validates\n    // the stable capability contract while retaining its own trusted adapters.\n    if (stableStringify(claimedBaseCapabilities) !== stableStringify(trustedBaseCapabilities)) {\n      throw new SurveyAssistantCapabilityMismatchError(\n        \"The editor and server use different survey assistant capabilities; refresh and retry.\",\n      );\n    }\n  }\n};\n"],"mappings":";;;AAyDA,MAAa,uCAAuC,EAClD,cACA,UACA,YAMA,cAAc,WACX,IAAI,QAAQ,CAAC,EACZ,YAAY,MAAM,cAAc,UAAU,UAAU,KAAK;AAE/D,MAAa,wBAAwB,EACnC,cACA,WAKA,cAAc,WAAW,IAAI,KAAK,QAAQ,CAAC,EAAE,cAAc,IAAI;AAEjE,MAAa,qCACX,iBACiC;CACjC,MAAM,6BAAa,IAAI,IAA4C;CACnE,MAAM,sBAAmD,CAAC;CAE1D,KAAK,MAAM,cAAc,cAAc;EACrC,MAAM,WAAW,gCAAgC,MAAM,WAAW,QAAQ;EAC1E,MAAM,WAAW,SAAS;EAC1B,IAAI,WAAW,IAAI,QAAQ,GACzB,MAAM,IAAI,MAAM,wDAAwD,SAAS,GAAG;EAEtF,IACE,SAAS,WAAW,mBACpB,CAAC,SAAS,oBAAoB,SAAS,aAAa,GAEpD,MAAM,IAAI,MACR,0CAA0C,SAAS,8BACrD;EAEF,IACE,SAAS,WAAW,mBACpB,WAAW,uBACX,CAAC,WAAW,iCACZ,CAAC,WAAW,UAEZ,MAAM,IAAI,MACR,iCAAiC,SAAS,uKAC5C;EAEF,MAAM,0BAA0B,IAAI,IAAI,SAAS,mBAAmB,CAAC,CAAC;EACtE,KAAK,MAAM,aAAa,WAAW,cAAc,CAAC,GAChD,IAAI,CAAC,wBAAwB,IAAI,UAAU,KAAK,GAC9C,MAAM,IAAI,MACR,yBAAyB,UAAU,MAAM,mBAAmB,SAAS,4CACvE;EAGJ,WAAW,IAAI,UAAU,UAAU;EACnC,oBAAoB,KAClB,gCAAgC,MAAM,KAAK,MAAM,KAAK,UAAU,QAAQ,CAAC,CAAC,CAC5E;CACF;CAKA,MAAM,wBAAwB,EAAE,WAHd,oBAAoB,MAAM,MAAM,UAChD,KAAK,SAAS,cAAc,MAAM,QAAQ,CAEJ,EAAE;CAE1C,OAAO;EACL,UAAU;GACR,GAAG;GACH,QAAQ,sBAAsB,qBAAqB;EACrD;EACA;CACF;AACF;AAEA,MAAa,mCACX,aAEA,SAAS,UACN,QAAQ,UAAU,MAAM,WAAW,eAAe,CAAC,CACnD,KAAK,UAAU,MAAM,QAAQ;AAElC,MAAa,mCAAmC,EAC9C,aACA,gBAIqC,EACrC,UAAU;CACR;CACA,mBAAmB;CACnB;CACA,QAAQ;CACR,qBAAqB,CAAC;CACtB,iBAAiB,CAAC;AACpB,EACF;AAEA,IAAa,yCAAb,cAA4D,MAAM;CAChE,OAAgB;CAEhB,YAAY,UAAU,wEAAwE;EAC5F,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;AAEA,MAAa,qCAAqC,EAChD,UACA,qBACA,oBAKU;CACV,MAAM,EAAE,QAAQ,eAAe,GAAG,0BAA0B;CAE5D,IAAI,kBADmB,sBAAsB,qBACV,KAAK,kBAAkB,eACxD,MAAM,IAAI,uCAAuC;CAGnD,IAAI,qBAAqB;EACvB,MAAM,4BAA4B,EAChC,iBAAiB,kBACjB,GAAG,iBACgF;EACrF,MAAM,0BAA0B,SAAS,UAAU,IAAI,wBAAwB;EAC/E,MAAM,0BACJ,oBAAoB,SAAS,UAAU,IAAI,wBAAwB;EAKrE,IAAI,gBAAgB,uBAAuB,MAAM,gBAAgB,uBAAuB,GACtF,MAAM,IAAI,uCACR,uFACF;CAEJ;AACF"}

package/dist/capabilities-default.d.mts

@@ -1,15 +1,16 @@
-import { Ut as AssistantItemCapabilityAdapter, qt as SurveyAssistantCapabilitySet } from "./index-Tnqv-yKW.mjs";
-
+import { Wt as AssistantItemCapabilityAdapter, qt as SurveyAssistantCapabilitySet } from "./index-Ciq7vHIs.mjs";
 //#region src/capabilities/default.d.ts
-declare const rootItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const groupItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const pageBreakItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const infoItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const choiceItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const formItemAssistantCapability: AssistantItemCapabilityAdapter;
-declare const defaultSurveyAssistantCapabilities: readonly [AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter];
-declare const defaultSurveyAssistantCapabilitySet: SurveyAssistantCapabilitySet;
-declare const getDefaultSurveyAssistantCapability: (itemType: string) => AssistantItemCapabilityAdapter | undefined;
+export declare const rootItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const groupItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const pageBreakItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const infoItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const choiceItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const formItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const consentItemAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const choiceMatrixAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const formMatrixAssistantCapability: AssistantItemCapabilityAdapter;
+export declare const defaultSurveyAssistantCapabilities: readonly [AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter];
+export declare const defaultSurveyAssistantCapabilitySet: SurveyAssistantCapabilitySet;
+export declare const getDefaultSurveyAssistantCapability: (itemType: string) => AssistantItemCapabilityAdapter | undefined;
 //#endregion
-export { choiceItemAssistantCapability, defaultSurveyAssistantCapabilities, defaultSurveyAssistantCapabilitySet, formItemAssistantCapability, getDefaultSurveyAssistantCapability, groupItemAssistantCapability, infoItemAssistantCapability, pageBreakItemAssistantCapability, rootItemAssistantCapability };
 //# sourceMappingURL=capabilities-default.d.mts.map

package/dist/capabilities-default.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities-default.d.mts","names":[],"sources":["../src/capabilities/default.ts"],"mappings":";;;cAoNa,2BAAA,EAA6B,8BAAA;AAAA,cAY7B,4BAAA,EAA8B,8BAAA;AAAA,cAsB9B,gCAAA,EAAkC,8BAAA;AAAA,cAsBlC,2BAAA,EAA6B,8BAAA;AAAA,cA6B7B,6BAAA,EAA+B,8BAAA;AAAA,cAyF/B,2BAAA,EAA6B,8BAAA;AAAA,cA2D7B,kCAAA,YAAkC,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA;AAAA,cASlC,mCAAA,EAEZ,4BAAA;AAAA,cAEY,mCAAA,GACX,QAAA,aACC,8BAAA"}
+{"version":3,"file":"capabilities-default.d.mts","names":[],"sources":["../src/capabilities/default.ts"],"mappings":";;qBAuMa,6BAA6B;qBAY7B,8BAA8B;qBAsB9B,kCAAkC;qBAsBlC,6BAA6B;qBA6B7B,+BAA+B;qBAsG/B,6BAA6B;qBA4D7B,gCAAgC;qBAkMhC,iCAA+B;qBAC/B,+BAA6B;qBAE7B,8CAAkC,gCAAA,gCAAA,gCAAA,gCAAA,gCAAA,gCAAA,gCAAA,gCAAA;qBAYlC,qCAAA;qBAIA,sCACX,qBACC"}