@case-framework/survey-assistant 0.7.0 → 0.9.0

package/dist/references/expressions.md

@@ -10,16 +10,17 @@ Use `survey_expression` for expression work. It is the expression capability bun
 
 ## JsonExpression
 
-Expression JSON has four node types:
+Expression JSON has five 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": [] }
+{ "type": "ownerState", "state": "disabled", "targetRef": { "ownerId": "<ownerId>" } }
 ```
 
-Optional `editorConfig` can contain `usedTemplate`, `label`, and `description`.
+Optional `editorConfig` contains only `usedTemplate`, `label`, and `description`; unknown keys are rejected. Missing argument-array operands are `null`, preserving their positions across JSON round trips. Required gaps are unfinished expressions, not false values. Optional single children such as a context key are omitted properties.
 
 ## Response Values And Variables
 
@@ -28,34 +29,37 @@ 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 "the respondent answered this slot." It never means a particular answer
+`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.
 
-Avoid accidental cycles in assistant-authored explicit item-level display-condition response
-dependencies, including direct self-reference and A depending on B while B depends on A. Shared
-survey integrity analysis reports these as advisory findings because responses can be populated
-before visibility is evaluated, including through prefills. Prefer an acyclic controlling source
-item unless the dependency is intentional. This analysis currently covers explicit item-level
-response edges; it does not model inherited group visibility or component-level dependency graphs.
-Component-level conditions may still use another response slot from the same item when that
-interaction is valid.
+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,
+semantic sections, hidden choice options and unselected follow-up inputs. With no visibility condition the target is visible. An authored visibility expression returning missing or false makes it inactive; a defined non-boolean result is inactive with a diagnostic. 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,
@@ -73,27 +77,76 @@ 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.
 
-Context variable types are `locale`, `participantFlag`, `customValue`, and `customExpression`.
+Context variable types are `locale`, `currentDate`, `participantFlag`, and `customValue`.
+`{ "type": "contextVariable", "contextType": "currentDate" }` returns the participant's current
+day as a full `date`. It takes no key; the host fixes it when the session starts and records it with
+the response, so submission validation and export replay see the same day. Opaque callbacks (`customExpression`) are not part of the grammar; use recorded custom values so player, submission validation and export replay agree.
 
 ## Functions
 
 Boolean: `and`, `or`, `not`.
 List containment: `list_contains`.
+List counting: `list_count(list)` returns the number of entries in any array value;
+`list_count(list, filter)` counts only entries that also appear in `filter`, a list of the same
+type. A missing list (for example an unanswered multiple choice) counts as `0`; use `isDefined`
+to tell unanswered from none selected. For "at least two of these options selected":
+`gte(list_count(<reference[] ref>, const(reference[], ["<optionId>", ...])), const(number, 2))`.
+Filter option ids must be declared option identities, as with `list_contains`.
 Equality/comparison: `eq`, `gt`, `gte`, `lt`, `lte`, `in_range`.
 Numeric aggregation: `sum`, `min`, `max`.
 String equality: `str_eq`.
-Date equality: `date_eq`.
+Conditional value: `if(condition, then, else)` returns `then` when the boolean condition is true
+and `else` when it is false; only the chosen branch is evaluated. `else` is optional (missing when
+omitted), and a missing condition returns missing rather than `else`. The result type is the
+branches' type: both branches must have the same type, and the usage checks it like any other
+result (e.g. a score uses number branches, a visibility condition boolean branches). Nest `if`
+calls for more than two cases, e.g. `if(c1, a, if(c2, b, c))`.
+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, unit)` returns the signed number of completed units in `a - b`. `unit` is a
+required string const: `"years"`, `"months"`, or `"days"`. Mixed precisions are compared at the
+coarser one (a year-only birth date gives calendar-year differences), and a unit finer than that
+precision returns undefined. Missing values propagate undefined; do not use timestamps or divide
+days to calculate ages. Age in years:
+`date_diff(contextVariable(currentDate), responseVariable(<birth date>), const(string, "years"))`.
+For an "at least N years old" check, use `gte(date_diff(...), const(number, N))`, which works
+for every birth-date precision. The anniversary form
+`date_lte(date_add_years(<birth date>, N), currentDate)` only works for full `YYYY-MM-DD` birth
+dates: for a year or month birth date it compares mismatched precisions and returns undefined.
+For full dates the two agree except on February 29 birthdays, which reach an anniversary on
+February 28 with the anniversary form and on March 1 with `date_diff`.
+
+Number and date inputs (and form-matrix number/date fields) take `min` / `max` bounds that are a
+literal or `{expression, fallback?}`. Use a response reference or arithmetic expression of the
+input's type. For example, a latest date seven days after another answer uses
+`date_add_days(responseVariable(...), const(number, 7))`. When the expression has no value (for
+example the referenced answer is empty), the bound does not apply, unless it has a `fallback`.
+Slider bounds from an expression require a `fallback`.
+Use set-config-expression with path `/min/expression` or `/max/expression` relative to the element
+config; an existing literal bound becomes the fallback. clear-config-expression on the same path
+restores the fallback, or removes a bound without one. The normal expression operations remain
+appropriate for item validations, prefills, and display conditions.
+Date 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 bound whose expression has no value does not apply, unless it has a `fallback`; then the
+fallback applies. Fixed bounds and fallbacks must leave at least one valid answer at the input's
+precision.
 
 Example: show an item when option "yes" is selected on choice item q1:
 
@@ -102,8 +155,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"
+      }
+    }
   ]
 }
 ```
@@ -115,209 +180,277 @@ 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"
+      }
+    }
   ]
 }
 ```
 
 ## New Items With Dependencies
 
-For a newly created source and dependent, use this operation order and expression placement.
-This pattern is item-type independent: `displayConditions` is a sibling of `config` on the
-raw item, never inside `config` or `translations`.
+For a newly created source and dependent, use this operation order and expression placement. This pattern is element-type independent: `visibility` is on its owner, beside `config`, never inside translations. A flow item condition applies to its complete body; an element condition applies only to that element. Replace `<root-group-id>` with the inspected root group ID.
 
 ```json
 [
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<root-group-id>"
+    },
     "item": {
-      "id": "routing_choice",
-      "key": "routing_choice",
-      "itemType": "choiceItem",
+      "id": "routing",
+      "itemType": "content",
       "config": {
-        "id": "routing_choice",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          { "id": "option_a", "key": "option_a" },
-          { "id": "option_b", "key": "option_b" }
-        ]
+        "body": {
+          "blocks": [
+            {
+              "kind": "layout",
+              "id": "routing-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-choice",
+                  "elementType": "choice",
+                  "config": {
+                    "slotId": "routing-slot",
+                    "variableName": "routing_choice",
+                    "presentation": "radio",
+                    "options": [
+                      {
+                        "id": "routing-a",
+                        "code": "A"
+                      },
+                      {
+                        "id": "routing-b",
+                        "code": "B"
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          ]
+        }
       }
     },
     "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" }
+      {
+        "ownerId": "routing",
+        "role": "title",
+        "locale": "en",
+        "plainText": "Choose an option"
+      },
+      {
+        "ownerId": "routing-a",
+        "role": "label",
+        "locale": "en",
+        "plainText": "Option A"
+      },
+      {
+        "ownerId": "routing-b",
+        "role": "label",
+        "locale": "en",
+        "plainText": "Option B"
+      }
     ]
   },
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<root-group-id>"
+    },
     "item": {
-      "id": "follow_up_a",
-      "key": "follow_up_a",
-      "itemType": "choiceItem",
+      "id": "routing-followup-a",
+      "itemType": "content",
       "config": {
-        "id": "follow_up_a",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          { "id": "yes", "key": "yes" },
-          { "id": "no", "key": "no" }
-        ]
-      },
-      "displayConditions": {
-        "root": {
-          "type": "function",
-          "functionName": "eq",
-          "arguments": [
-            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
-            { "type": "const", "value": { "type": "reference", "value": "option_a" } }
+        "body": {
+          "blocks": [
+            {
+              "kind": "layout",
+              "id": "routing-followup-a-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-followup-a-text",
+                  "elementType": "text",
+                  "config": {
+                    "slotId": "routing-followup-a-slot",
+                    "variableName": "followup_a",
+                    "presentation": "long"
+                  }
+                }
+              ]
+            }
           ]
         }
+      },
+      "visibility": {
+        "type": "function",
+        "functionName": "eq",
+        "arguments": [
+          {
+            "type": "responseVariable",
+            "variableRef": {
+              "slotId": "routing-slot",
+              "method": "get"
+            }
+          },
+          {
+            "type": "const",
+            "value": {
+              "type": "reference",
+              "value": "routing-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" }
+      {
+        "ownerId": "routing-followup-a",
+        "role": "title",
+        "locale": "en",
+        "plainText": "Details for option A"
+      }
     ]
   },
   {
     "kind": "create-item",
-    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "target": {
+      "parentItemId": "<root-group-id>"
+    },
     "item": {
-      "id": "follow_up_b",
-      "key": "follow_up_b",
-      "itemType": "choiceItem",
+      "id": "routing-followup-b",
+      "itemType": "content",
       "config": {
-        "id": "follow_up_b",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          { "id": "yes", "key": "yes" },
-          { "id": "no", "key": "no" }
-        ]
-      },
-      "displayConditions": {
-        "root": {
-          "type": "function",
-          "functionName": "eq",
-          "arguments": [
-            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
-            { "type": "const", "value": { "type": "reference", "value": "option_b" } }
+        "body": {
+          "blocks": [
+            {
+              "kind": "layout",
+              "id": "routing-followup-b-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-followup-b-text",
+                  "elementType": "text",
+                  "config": {
+                    "slotId": "routing-followup-b-slot",
+                    "variableName": "followup_b",
+                    "presentation": "long"
+                  }
+                }
+              ]
+            }
           ]
         }
+      },
+      "visibility": {
+        "type": "function",
+        "functionName": "eq",
+        "arguments": [
+          {
+            "type": "responseVariable",
+            "variableRef": {
+              "slotId": "routing-slot",
+              "method": "get"
+            }
+          },
+          {
+            "type": "const",
+            "value": {
+              "type": "reference",
+              "value": "routing-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" }
+      {
+        "ownerId": "routing-followup-b",
+        "role": "title",
+        "locale": "en",
+        "plainText": "Details for option B"
+      }
     ]
   }
 ]
 ```
 
-Use the same placement on other interactive item types; only their `itemType`, `config`, and
-translations change. The validator makes response slots from earlier creates available to later
-creates in this one operations array.
-
-## survey_expression Mutations
+The validator makes response slots from earlier creates available to later creates in this one operations array. This example creates separate conditional questions. For content directly below a radio/checkbox option, use an option-inline follow-up instead; it already has an activation gate.
 
-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
-{
-  "kind": "set-item-display-condition",
-  "itemId": "followup_yes",
-  "expression": {
-    "type": "function",
-    "functionName": "eq",
-    "arguments": [
-      { "type": "responseVariable", "variableRef": "q1...get...q1" },
-      { "type": "const", "value": { "type": "reference", "value": "yes" } }
-    ]
-  }
-}
-```
+## Disabled state and applicability
 
-Component visibility:
-`set-component-display-condition` with `itemId`, `componentId`, and a boolean `expression`.
-For choice options the component id is usually the option id. For form fields or field groups, inspect item details/raw JSON first.
+`ownerState` with `state: "disabled"` is the stored form of `isDisabled(owner)`. It reads the configured and inherited disabling of an inspected structural owner. It always returns boolean. It does not report visibility, answer presence or whether a choice cap permits a change. Answer and state dependencies share one cycle-checked graph. A parent reading its own child's disabled state is cyclic because the child inherits from that parent.
 
-Component disabled state:
-`set-component-disabled-condition` with `itemId`, `componentId`, and a boolean `expression`.
+Active disabled answers are retained, readable in expressions and submitted. Participant writes are rejected while the whole input or an ancestor is disabled; initialization has its separate engine-owned path. Validation cannot block on targets the participant cannot change. Disabled checkbox options are locked; single-choice replacement can leave a disabled selection for an enabled destination. Hidden answers remain unavailable instead. Use visibility for “not applicable” and disabled for locking, not as a way of removing answers from data.
 
-Validation expressions:
-`set-validation-expression` with `itemId`, `validationKey`, and a boolean `expression`.
-Add a matching validation message translation when respondents need visible feedback.
+“Selected and enabled” is an authoring shortcut expanded into `and(selectionTest, not(ownerState(...)))`. Use eq for single choice, list_contains for checkbox selection. It is not a new persisted function. Disabled ancestors also make this false, including intentionally read-only prefilled items. Do not use the shortcut where the condition should still honor such answers. Mutual selected-and-enabled disabling may create a cycle; ordinary selection-based exclusivity avoids adding that state loop.
 
-Prefills:
-`set-prefill` with `itemId` and a full prefill object. `when`, when present, must return boolean.
-Prefill source can be `static`, `expression`, `templateValue`, or `previousResponse`.
+## Creation and expression mutations
 
-Template values:
-`set-template-value` with `templateKey` and `templateValue`.
-The template expression should match `returnType`; `date2string` also needs `dateFormat`.
+Create source owners before their dependents. New owners may carry `visibility`, `disabled`, prefills and validation expressions in their creation payloads. For existing owners, use `survey_expression` with these mutations:
 
-Clear operations:
-`clear-item-display-condition`, `clear-component-display-condition`,
-`clear-component-disabled-condition`, `clear-validation-expression`,
-`clear-prefill`, and `clear-template-value`.
+- `set-condition`: `ownerId`, `property` (`visibility` or `disabled`), boolean `expression`.
+- `clear-condition`: the same owner and property; absent visibility means visible and absent disabling means enabled, subject to ancestors.
+- `set-config-expression`: `elementId`, inspected config-relative JSON Pointer `path`, and `expression`. The exact field must be declared as an expression by the installed element schema, including custom definitions.
+- `clear-config-expression`: the same element and path; schema-required fields cannot be cleared.
+- `set-validation-rule`: `itemId` and complete `rule` (`id`, nonempty `targets` slot IDs, boolean `expression`, optional boolean `when`, optional `phase: page|submit`). Its localized message belongs to that rule ID's `message` role.
+- `remove-validation-rule`: `itemId`, `ruleId`.
+- `set-prefill`: `elementId`, `slotId`, complete `prefill`.
+- `clear-prefill`: `elementId`, `slotId`, `prefillId`.
+- `set-template-value`: `templateKey`, complete `templateValue`.
+- `clear-template-value`: `templateKey`.
 
-## Storage Locations
+Inspect exact owner IDs and expression locations. Conditions live directly on their annotated owner; prefills live at `element.prefills[slotId]`; validation rules live in `contentItem.config.validationRules`. Never reconstruct a location from a display label or old component path. Rules target slots owned by their item and cannot block when no target is active and changeable.
 
-Item display condition:
-`/surveyItems/<itemIndex>/displayConditions/root`
-
-Component display condition:
-`/surveyItems/<itemIndex>/displayConditions/components/<componentId>`
-
-Component disabled condition:
-`/surveyItems/<itemIndex>/disabledConditions/components/<componentId>`
-
-Item validation expression:
-`/surveyItems/<itemIndex>/validations/<validationKey>`
-
-Prefills:
-`/surveyItems/<itemIndex>/prefills`
-
-Template values:
-`/templateValues/<templateValueKey>`
+Page rules that read another item's answers can prevent reaching those answers on a later page. Inspect the shared `cross-item-page-rule` advisory; use submit-phase validation or an explicit unanswered-dependency condition when appropriate. Do not silently change an existing rule's phase.
 
 ## Prefills
 
-Prefill shape:
+Prefills initialize **once** when creating a new session, including hidden inputs, disabled inputs and closed follow-ups. They do not reapply while answering, after clearing a field, or on resume. A resumed session restores its versioned snapshot without new prefill lookups. Hiding/disabling retains initialized and participant-entered answers. Never use repeated prefilling to enforce exclusivity.
+
+A prefill has `id`, optional boolean `when`, optional `apply: "ifEmpty"`, and `source`. Its target is the surrounding element's slot key, not an itemResponse/field/embeddedField descriptor.
 
 ```json
 {
-  "id": "prefill-1",
-  "target": { "type": "itemResponse" },
-  "when": { "type": "const", "value": { "type": "boolean", "value": true } },
-  "apply": "ifEmpty",
-  "source": { "type": "static", "value": { "type": "string", "value": "x" } }
+  "kind": "set-prefill",
+  "elementId": "name-input",
+  "slotId": "name-slot",
+  "prefill": {
+    "id": "name-initial",
+    "source": { "type": "static", "value": { "type": "string", "value": "Example" } }
+  }
 }
 ```
 
-Targets:
-
-- `{ "type": "itemResponse" }`
-- `{ "type": "field", "fieldId": "<fieldId>" }`
-- `{ "type": "embeddedField", "optionId": "<optionId>", "fieldId": "<fieldId>" }`
-
-Sources:
+Sources are static typed value, expression, templateValue key, or previousResponse with `ref: {surveyKey?, slotId}` and optional `ifUnsupported: "skip"`. Inspect host capabilities before depending on previous responses. Values must match the target slot's domain; scores/computed slots are not prefill targets. Prefill dependencies also participate in cycle checking.
 
-- `static`: direct ResponseValue.
-- `expression`: JsonExpression.
-- `templateValue`: `{ "key": "<templateValueKey>" }`.
-- `previousResponse`: `{ "ref": { "surveyKey"?, "itemId", "target"? }, "ifUnsupported": "skip" }`.
+Do not assume a host provides previous responses. Survey Mode currently does not; it rejects publication with a required unsupported source. Use `ifUnsupported: "skip"` only when omitting that initial value is intentional. Invalid derived prefill values are skipped with a located diagnostic and later candidates may apply; do not treat that as permission to author incompatible values.
 
 ## Template Values
 
@@ -327,14 +460,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`.
+Date formatting template values use `type: "formatDate"`, `returnType: "string"`, and `dateFormat`.
 
 ## Bounded context and atomic batches
 
-`survey_expression` action `context` filters response slots and expression locations with `itemIds` (ids, keys, or fullKeys). 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.
+`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.