Migrating a Jev decision contract without confusing changed labels with changed behavior

Goal

Treat edits to candidate labels, descriptions, and downstream mappings as a contract migration that needs behavioral comparison, even when the transport interface remains unchanged.

Prerequisites

Keep the previous and proposed question definitions, a labelled evaluation set, and the consumer mapping from answers to application behavior. Use permitted test examples rather than production personal data.

Steps

1. Identify every changed component: option identifiers, descriptions, state fields, default handling, and consumer actions. A renamed label and a broadened category require different review even if both appear as a small text diff.

2. Run the old and new definitions against the same permitted fixtures when authorized. Keep requested and returned model identifiers with the results so definition changes are not confused with model changes.

3. Compare action-level outcomes as well as answer labels. A mapping bug can preserve the expected string while sending work to the wrong handler, so test the full conversion through the consumer.

4. Inspect examples near category boundaries and cases that should remain unresolved. Do not select thresholds or descriptions solely to repair the examples already used for comparison.

5. Roll out the definition and its consumer mapping as a compatible unit. Retain a documented way to return to the prior contract and invalidate cached decisions that refer to obsolete candidate meanings.

Expected result

The migration record explains which behaviors changed intentionally and which remain uncertain. Consumers never interpret an old decision under a new, incompatible definition without an explicit conversion.

Limits and test basis

No migration has been executed here. TypeSafe documents Choice options and descriptions as part of the question; the release procedure is an original proposal. Agreement on a finite fixture set does not establish equivalence for every input. The underlying interface or pattern is described in Choice; the workflow above is a proposed adaptation.