@case-framework/survey-assistant 0.6.0 → 0.8.0

package/dist/references/expressions.md

@@ -5,6 +5,8 @@ Use `survey_expression` for expression work. It is the expression capability bun
 - `action: "context"` returns available response refs and optional existing expression locations.
 - `action: "prepare"` validates expression refs/return types and registers a candidate change set.
 - Prefer this tool over hand-written raw JSON Patch for expression-bearing locations.
+- Provider adapters normalize optional fields when strict tool calling requires nullable wire
+  properties. Supply only the fields used by the chosen action.
 
 ## JsonExpression
 
@@ -12,7 +14,7 @@ Expression JSON has four node types:
 
 ```json
 { "type": "const", "value": { "type": "boolean", "value": true } }
-{ "type": "responseVariable", "variableRef": "<itemId>...get...<slotId>" }
+{ "type": "responseVariable", "variableRef": { "slotId": "<slotId>", "method": "get" } }
 { "type": "contextVariable", "contextType": "locale" }
 { "type": "function", "functionName": "and", "arguments": [] }
 ```
@@ -26,18 +28,38 @@ Response values are typed objects:
 - string: `{ "type": "string", "value": "abc" }`
 - number: `{ "type": "number", "value": 42 }`
 - boolean: `{ "type": "boolean", "value": true }`
-- date: `{ "type": "date", "value": 1767225600000 }`
+- date: `{ "type": "date", "value": "2026-01-01" }`
 - duration: `{ "type": "duration", "value": 3, "unit": "days" }`
 - reference: `{ "type": "reference", "value": "<optionId>" }`
 - arrays use `string[]`, `number[]`, `date[]`, `duration[]`, `reference[]`.
 
-Response variable refs use this exact string format:
-`<itemId>...<method>...<slotId>`
+Response variable refs are structured objects: `{ "slotId": "<persistent-slot-id>", "method": "get" }`. There is no item ID, dotted path, variable name, or encoded string in a reference.
 
 Methods:
 
-- `get`: returns the current slot value.
-- `isDefined`: returns boolean true when a response exists.
+- `get`: returns the current active slot value.
+- `isDefined`: returns boolean true when an active response exists.
+
+`isDefined` means only "this slot currently has an active answer." It never means a particular answer
+such as Yes, selected, eligible, consented, or has children. When the user's condition names or
+implies a choice, inspect the source choice item's exact option ids and labels, then compare the
+`get` response with that option's reference using `eq` (single choice) or `list_contains`
+(multiple choice). Do not substitute `isDefined` merely because the exact option id is not yet
+known.
+
+Visibility dependencies must be acyclic. The runtime rejects self-reference, mutual
+question dependencies, parent groups controlled by their descendants, and cycles through
+conditional components or computed scores. Prefills do not make these cycles valid.
+Use an independent controlling answer or serialized custom context value. A component may
+reference another slot in the same item only when its active value does not depend on that
+component's visibility. Repair rejected changes using the returned retry linkage.
+
+Hidden answers remain stored for the session and return when shown again, but are unavailable
+to expressions, validation, scoring and submission while hidden. `get` returns undefined and
+`isDefined` returns false for an inactive answer. This includes hidden groups, matrix rows,
+form groups, hidden choice options and unselected embedded fields. Display conditions with
+undefined or non-boolean results hide their target. Visibility cannot use `customExpression`
+callbacks; supply serialized `customValue` context instead.
 
 Never invent response refs. Use the current context response-slots scope or item details.
 This rule is item-type independent: preserve every item id, slot id, component/validation key,
@@ -55,13 +77,12 @@ in its `create-item.item` object in one `survey_change` call. When a genuine dep
 separate calls, inspect the updated request-scoped draft and use `survey_expression` against the
 newly available ids and response slots.
 
-Each response slot defined by a source item's config is available as
-`<sourceItemId>...get...<slotId>`, with a boolean presence check at
-`<sourceItemId>...isDefined...<slotId>`. Use the slot's actual value type to choose the
+Each declared response slot is available as `{ "slotId": "<slotId>", "method": "get" }`, with a presence check using the same slot ID and `method: "isDefined"`. Use the slot's actual value type to choose the
 function and constant. For example, a single-choice `reference` slot uses `eq` with a
 `reference` const; this is only one typed case, not a restriction on source item types.
 Always check the response slot value type before choosing a function:
 
+- Consent items return `boolean` in their persistent `config.slotId`; compare with `eq` and boolean `true` for agreement or `false` for refusal. Unanswered is neither. `isDefined` means either decision was recorded. Display conditions hide dependent content while retaining session answers; hidden items are omitted from submission.
 - Single-choice choice items return `reference`; compare them with `eq` and a `reference` const.
 - Multiple-choice choice items return `reference[]`; check selected options with `list_contains` and a `reference` const.
 - `list_contains` must receive `string[]` + `string` or `reference[]` + `reference`. Never use it with a single `reference` response.
@@ -75,7 +96,26 @@ List containment: `list_contains`.
 Equality/comparison: `eq`, `gt`, `gte`, `lt`, `lte`, `in_range`.
 Numeric aggregation: `sum`, `min`, `max`.
 String equality: `str_eq`.
-Date equality: `date_eq`.
+Calendar dates use `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`; numeric timestamps and date-time strings are invalid. Preserve the answer's precision.
+
+Date comparisons: `date_eq`, `date_gt`, `date_gte`, `date_lt`, `date_lte` (two date arguments).
+Equality includes precision; ordering requires matching precision and returns undefined otherwise.
+`date_min` / `date_max` take one or more dates of matching precision and return a date.
+`date_add_days`, `date_add_months`, `date_add_years` take a date and a signed integer number.
+Offsets retain precision; month/year offsets clamp to the last day of the destination month.
+Nonzero day offsets require full dates, nonzero month offsets require at least month precision.
+`date_diff(a, b)` returns signed `a - b`, in days for full dates, months for month values,
+or years for year values. Both arguments must have matching precision. Missing arguments' values
+propagate undefined; do not use timestamps or divide by seconds to calculate calendar differences.
+
+Form and form-matrix `minDate` / `maxDate` rules can use `valueExpression` instead of `value`.
+Use a date response reference or date arithmetic expression. For example, a latest date seven days
+after another answer uses `date_add_days(responseVariable(...), const(number, 7))`.
+Use the form-field or matrix configuration operation to set these field rules. The normal expression
+operations remain appropriate for item validations, prefills, and display conditions.
+Bounds are inclusive: minimum uses the start of its calendar period, maximum uses its end.
+The entire answer period must fit within the bound. An unanswered optional date remains valid;
+a supplied answer with an unresolved bound fails validation until the source is available.
 
 Example: show an item when option "yes" is selected on choice item q1:
 
@@ -84,8 +124,20 @@ Example: show an item when option "yes" is selected on choice item q1:
   "type": "function",
   "functionName": "eq",
   "arguments": [
-    { "type": "responseVariable", "variableRef": "q1...get...q1" },
-    { "type": "const", "value": { "type": "reference", "value": "yes" } }
+    {
+      "type": "responseVariable",
+      "variableRef": {
+        "slotId": "q1",
+        "method": "get"
+      }
+    },
+    {
+      "type": "const",
+      "value": {
+        "type": "reference",
+        "value": "yes"
+      }
+    }
   ]
 }
 ```
@@ -97,8 +149,20 @@ Example: multiple-select contains option "apple" when the inspected response slo
   "type": "function",
   "functionName": "list_contains",
   "arguments": [
-    { "type": "responseVariable", "variableRef": "q2...get...q2" },
-    { "type": "const", "value": { "type": "reference", "value": "apple" } }
+    {
+      "type": "responseVariable",
+      "variableRef": {
+        "slotId": "q2",
+        "method": "get"
+      }
+    },
+    {
+      "type": "const",
+      "value": {
+        "type": "reference",
+        "value": "apple"
+      }
+    }
   ]
 }
 ```
@@ -113,91 +177,175 @@ raw item, never inside `config` or `translations`.
 [
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<parent-group-id>"
+    },
     "item": {
       "id": "routing_choice",
-      "key": "routing_choice",
       "itemType": "choiceItem",
       "config": {
         "id": "routing_choice",
         "maxSelection": 1,
         "shuffleOptions": false,
         "options": [
-          { "id": "option_a", "key": "option_a" },
-          { "id": "option_b", "key": "option_b" }
-        ]
+          {
+            "id": "option_a",
+            "code": "option_a"
+          },
+          {
+            "id": "option_b",
+            "code": "option_b"
+          }
+        ],
+        "variableName": "routing_choice"
       }
     },
     "translations": [
-      { "locale": "en", "contentKey": "title", "plainText": "Choose an option" },
-      { "locale": "en", "contentKey": "options.option_a.label", "plainText": "Option A" },
-      { "locale": "en", "contentKey": "options.option_b.label", "plainText": "Option B" }
+      {
+        "locale": "en",
+        "contentKey": "title",
+        "plainText": "Choose an option"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.option_a.label",
+        "plainText": "Option A"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.option_b.label",
+        "plainText": "Option B"
+      }
     ]
   },
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<parent-group-id>"
+    },
     "item": {
       "id": "follow_up_a",
-      "key": "follow_up_a",
       "itemType": "choiceItem",
       "config": {
         "id": "follow_up_a",
         "maxSelection": 1,
         "shuffleOptions": false,
         "options": [
-          { "id": "yes", "key": "yes" },
-          { "id": "no", "key": "no" }
-        ]
+          {
+            "id": "yes",
+            "code": "yes"
+          },
+          {
+            "id": "no",
+            "code": "no"
+          }
+        ],
+        "variableName": "follow_up_a"
       },
       "displayConditions": {
         "root": {
           "type": "function",
           "functionName": "eq",
           "arguments": [
-            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
-            { "type": "const", "value": { "type": "reference", "value": "option_a" } }
+            {
+              "type": "responseVariable",
+              "variableRef": {
+                "slotId": "routing_choice",
+                "method": "get"
+              }
+            },
+            {
+              "type": "const",
+              "value": {
+                "type": "reference",
+                "value": "option_a"
+              }
+            }
           ]
         }
       }
     },
     "translations": [
-      { "locale": "en", "contentKey": "title", "plainText": "Follow-up for option A" },
-      { "locale": "en", "contentKey": "options.yes.label", "plainText": "Yes" },
-      { "locale": "en", "contentKey": "options.no.label", "plainText": "No" }
+      {
+        "locale": "en",
+        "contentKey": "title",
+        "plainText": "Follow-up for option A"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.yes.label",
+        "plainText": "Yes"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.no.label",
+        "plainText": "No"
+      }
     ]
   },
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<parent-group-id>"
+    },
     "item": {
       "id": "follow_up_b",
-      "key": "follow_up_b",
       "itemType": "choiceItem",
       "config": {
         "id": "follow_up_b",
         "maxSelection": 1,
         "shuffleOptions": false,
         "options": [
-          { "id": "yes", "key": "yes" },
-          { "id": "no", "key": "no" }
-        ]
+          {
+            "id": "yes",
+            "code": "yes"
+          },
+          {
+            "id": "no",
+            "code": "no"
+          }
+        ],
+        "variableName": "follow_up_b"
       },
       "displayConditions": {
         "root": {
           "type": "function",
           "functionName": "eq",
           "arguments": [
-            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
-            { "type": "const", "value": { "type": "reference", "value": "option_b" } }
+            {
+              "type": "responseVariable",
+              "variableRef": {
+                "slotId": "routing_choice",
+                "method": "get"
+              }
+            },
+            {
+              "type": "const",
+              "value": {
+                "type": "reference",
+                "value": "option_b"
+              }
+            }
           ]
         }
       }
     },
     "translations": [
-      { "locale": "en", "contentKey": "title", "plainText": "Follow-up for option B" },
-      { "locale": "en", "contentKey": "options.yes.label", "plainText": "Yes" },
-      { "locale": "en", "contentKey": "options.no.label", "plainText": "No" }
+      {
+        "locale": "en",
+        "contentKey": "title",
+        "plainText": "Follow-up for option B"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.yes.label",
+        "plainText": "Yes"
+      },
+      {
+        "locale": "en",
+        "contentKey": "options.no.label",
+        "plainText": "No"
+      }
     ]
   }
 ]
@@ -209,6 +357,10 @@ creates in this one operations array.
 
 ## survey_expression Mutations
 
+The shapes below are the canonical mutations. Send the complete array once as `mutations`; the
+server validates every entry against these canonical shapes before changing the request-scoped
+draft.
+
 Item visibility:
 
 ```json
@@ -219,8 +371,20 @@ Item visibility:
     "type": "function",
     "functionName": "eq",
     "arguments": [
-      { "type": "responseVariable", "variableRef": "q1...get...q1" },
-      { "type": "const", "value": { "type": "reference", "value": "yes" } }
+      {
+        "type": "responseVariable",
+        "variableRef": {
+          "slotId": "q1",
+          "method": "get"
+        }
+      },
+      {
+        "type": "const",
+        "value": {
+          "type": "reference",
+          "value": "yes"
+        }
+      }
     ]
   }
 }
@@ -277,10 +441,24 @@ Prefill shape:
 ```json
 {
   "id": "prefill-1",
-  "target": { "type": "itemResponse" },
-  "when": { "type": "const", "value": { "type": "boolean", "value": true } },
+  "target": {
+    "type": "itemResponse"
+  },
+  "when": {
+    "type": "const",
+    "value": {
+      "type": "boolean",
+      "value": true
+    }
+  },
   "apply": "ifEmpty",
-  "source": { "type": "static", "value": { "type": "string", "value": "x" } }
+  "source": {
+    "type": "static",
+    "value": {
+      "type": "string",
+      "value": "x"
+    }
+  }
 }
 ```
 
@@ -305,8 +483,20 @@ Template value shape:
 {
   "type": "default",
   "returnType": "string",
-  "expression": { "type": "const", "value": { "type": "string", "value": "x" } }
+  "expression": {
+    "type": "const",
+    "value": {
+      "type": "string",
+      "value": "x"
+    }
+  }
 }
 ```
 
 Date formatting template values use `type: "date2string"`, `returnType: "string"`, and `dateFormat`.
+
+## Bounded context and atomic batches
+
+`survey_expression` action `context` filters response slots and expression locations with `itemIds` (exact persistent item IDs). Follow `nextCursor` with the same filter and `limit` until absent; restart after a draft mutation. The returned model text contains the actual page and distinguishes filtered totals from the survey-wide response-slot count. For a controlling question outside the filter, omit itemIds and cursor to retrieve the survey-wide catalog. Unresolved identifiers are reported explicitly, not as evidence that an item has no response.
+
+A `prepare` mutation array is executed in order within one atomic delta. Later mutations see earlier additions, replacements, and removals, including new containers and shifted prefill indexes. If any mutation fails, none of the delta is staged. Retry all requested mutations from that rejected delta; `pendingRepairs` tracks every remaining operation and surface. For missing or invalid targets, use the indicated `retryOfChangeIds` with the complete corrected input. If an expression location is already empty, inspect and acknowledge that rejected request with a linked `survey_change` using `operations: []`; other identifiable pending edits remain required. Clearing a condition is not a repair of a requested condition change.

package/dist/references/fair-by-design.md

@@ -14,7 +14,7 @@ not a universal override of the user's request or an established survey conventi
 
 1. **Presentation:** respondent-visible questions, instructions, and answer labels. These are
    localized content and may be reworded.
-2. **Stored identifiers and codes:** stable item and option identifiers, coding keys, typed values,
+2. **Stored identifiers and codes:** stable item and option identifiers, variable names, typed values,
    and standard formats. These are for machines and should not depend on display language.
 3. **Metadata:** definitions, labels for codes, units, data types, missing-value meanings, versions,
    provenance, and mappings to standards. Meaning belongs here rather than being packed into a
@@ -22,13 +22,13 @@ not a universal override of the user's request or an established survey conventi
 
 Do not use a respondent-visible label as though it were a stable stored code. Do not expose a raw
 identifier as respondent wording. In CASE, visible item, option, field, and validation text belongs
-in locale translations; ids, keys, option values, and response-slot references remain exact data.
+in locale translations; IDs, variable names, option codes, and response-slot references remain exact data.
 
-## Identifiers and coding keys
+## Identifiers and variable names
 
-- Preserve stable internal ids and existing keys unless the user asks to change them. Never
+- Preserve stable internal ids and existing variable names unless the user asks to change them. Never
   silently repurpose an existing identifier when meaning changes.
-- When FAIR item-key naming is relevant, start with a letter; use lowercase ASCII letters, digits,
+- When FAIR-oriented variable naming is relevant, start with a letter; use lowercase ASCII letters, digits,
   and underscores; use `snake_case`; stay at or below 32 characters; avoid programming and
   database reserved words; prefer a stable, language-neutral English concept name; reuse the same
   concept name across waves and studies; use established instrument prefixes and sortable item
@@ -37,7 +37,7 @@ in locale translations; ids, keys, option values, and response-slot references r
   metadata.
 - For a standard instrument, preserve its established identity and predictable structure, such as
   an instrument prefix plus a zero-padded item number, rather than inventing unrelated names.
-- Choice option ids, keys, and values should be stable and coding-friendly. Their localized labels
+- Choice option IDs and export codes should be stable and coding-friendly. Their localized labels
   remain separate translations.
 - Follow an explicit user-supplied identifier or established local convention when FAIR naming was
   not requested. If a FAIR alternative would materially help, explain the tradeoff rather than
@@ -51,9 +51,7 @@ in locale translations; ids, keys, option values, and response-slot references r
 - Reuse established code lists and formats when the task calls for interoperability: ISO 8601 for
   dates, ISO 3166 for countries, ISO 639 for languages, UCUM for units, and appropriate domain
   vocabularies such as LOINC or SNOMED CT when supported and relevant.
-- Treat not applicable, skipped by routing, do not know, refused, and not asked as distinct missing
-  reasons. Never invent an ordinary numeric value such as `99` or `-9` that could be analyzed as a
-  real response unless the surrounding data model explicitly declares and documents it as missing.
+- The current response envelope distinguishes typed answers from missing answers. It does not encode every missingness reason. Explain that limitation; do not claim skipped, refused, not asked and not applicable are automatically distinguishable. Explicit questionnaire options can represent such meanings when deliberately authored. Never conflate absent answers with zero, false, or an empty selection. Do not invent sentinel values.
 - Do not invent CASE fields or ad hoc codes to simulate missing-value semantics that the installed
   editor capabilities do not support. Explain the capability gap instead.
 
@@ -78,3 +76,5 @@ capabilities before changing existing identifiers, codes, values, or metadata. D
 rewrite a survey merely because this reference was loaded. Apply the parts material to the user's
 goal, state important tradeoffs, and identify platform-level FAIR requirements that remain outside
 the editor.
+
+These naming rules are CASE project conventions supporting FAIR practice, not requirements imposed by FAIR. Names alone do not make data FAIR; metadata, provenance, access, licensing and documented meaning remain necessary.