viv-compiler 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

viv_compiler/{utils/_version.py → _version.py}

@@ -1,2 +1,2 @@
 # This is programmatically updated by viv/scripts/bump_version.sh
-__version__ = "0.1.0"
+__version__ = "0.1.2"

viv_compiler/cli.py

@@ -10,6 +10,8 @@ import traceback
 import viv_compiler.config
 from pathlib import Path
 from importlib import resources
+
+from viv_compiler import VivCompileError
 from .api import compile_from_path, get_version
 from viv_compiler.types import CompiledContentBundle
 
@@ -189,10 +191,9 @@ def _invoke_compiler(args: argparse.Namespace) -> CompiledContentBundle:
         except Exception:
             pass
         sys.exit(1)
-    except Exception as e:
-        print(f"Error encountered during compilation: {e}", file=sys.stderr)
-        if args.debug:
-            traceback.print_exc()
+    except VivCompileError as e:
+        cause = e.__cause__ or e
+        print(f"Error encountered during compilation:\n\n{cause}\n", file=sys.stderr)
         sys.exit(1)
 
 

viv_compiler/config/config.py

@@ -25,9 +25,9 @@ NEGATABLE_EXPRESSION_TYPES = {
     ExpressionDiscriminator.CONJUNCTION,
     ExpressionDiscriminator.DISJUNCTION,
     ExpressionDiscriminator.ENTITY_REFERENCE,
-    ExpressionDiscriminator.LOCAL_VARIABLE_REFERENCE,
     ExpressionDiscriminator.LOOP,
     ExpressionDiscriminator.MEMBERSHIP_TEST,
+    ExpressionDiscriminator.SYMBOL_REFERENCE,
     ExpressionDiscriminator.TROPE_FIT_EXPRESSION,
 }
 
@@ -56,28 +56,21 @@ REACTION_FIELD_DEFAULT_OPTIONS = {
     "abandonmentConditions": [],
 }
 
-# The path to which the global-variable sigil `$` expands. This sigil is really just syntactic sugar for
+# Name for the special action self-reference role, which is always bound to the action itself
+ACTION_SELF_REFERENCE_ROLE_NAME = 'this'
+
+# A set containing the special role names that are automatically created by Viv at various points
+SPECIAL_ROLE_NAMES = {'hearer', ACTION_SELF_REFERENCE_ROLE_NAME}
+
+# The path to which the scratch-variable sigil `$` expands. This sigil is really just syntactic sugar for
 # the path `@this.scratch`, which stores a blackboard local to a performed action. For instance, the scratch
-# operation `$foo.bar = 99` is syntactic sugar for the expression `@this.scratch.foo.bar = 99`.
-GLOBAL_VARIABLE_REFERENCE_ANCHOR = "this"
-GLOBAL_VARIABLE_REFERENCE_PATH_PREFIX = [{
+# operation `$@foo.bar = 99` is syntactic sugar for the expression `@this.scratch.foo.bar = 99`.
+SCRATCH_VARIABLE_REFERENCE_ANCHOR = ACTION_SELF_REFERENCE_ROLE_NAME
+SCRATCH_VARIABLE_REFERENCE_PATH_PREFIX = [{
     "type": ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME,
     "name": "scratch",
 }]
 
-# The path to which the local-variable sigil `$$` expands. This sigil is really just a property lookup in
-# the special `__locals__` field of an evaluation context, which is a temporary store for scoped local
-# variables. For instance, the local-variable reference `$$c` defines an attempt to access `__locals__.c`
-# in an evaluation context. Unlike the `$` sigil, this is not syntactic sugar, since the Viv author has
-# no other way to reference local variables.
-LOCAL_VARIABLE_REFERENCE_PATH = ["__locals__"]
-
-# Name for the variable to which each character is set when computing their salience for an action
-SALIENCES_VARIABLE_NAME = "c"
-
-# Name for the variable to which each character is set when computing their associations for an action
-ASSOCIATIONS_VARIABLE_NAME = "c"
-
 # A default salience value, to be used when the API caller does not provide one
 DEFAULT_SALIENCE_VALUE = 1.0
 
@@ -86,3 +79,9 @@ DEFAULT_ASSOCIATIONS_VALUE = []
 
 # A default reaction priority value, to be used when the API caller does not provide one
 DEFAULT_REACTION_PRIORITY_VALUE = 1.0
+
+# A list containing the names of action fields in which assignments are permitted
+ACTION_FIELDS_PERMITTING_ASSIGNMENTS = ("scratch", "effects",)
+
+# A list containing the names of action fields in which reactions are permitted
+ACTION_FIELDS_PERMITTING_REACTIONS = ("reactions",)

viv_compiler/core/core.py

@@ -106,7 +106,7 @@ def _honor_user_supplied_config_parameters(
     """
     viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["saliences"] = {
         "default": {'type': 'float', 'value': default_salience},
-        "variable": viv_compiler.config.SALIENCES_VARIABLE_NAME,
+        "variable": None,
         "body": [],
     }
     default_associations_expression = {
@@ -115,7 +115,7 @@ def _honor_user_supplied_config_parameters(
     }
     viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["associations"] = {
         "default": default_associations_expression,
-        "variable": viv_compiler.config.ASSOCIATIONS_VARIABLE_NAME,
+        "variable": None,
         "body": [],
     }
     viv_compiler.config.REACTION_FIELD_DEFAULT_OPTIONS["priority"] = {

viv_compiler/core/metadata.py

@@ -33,15 +33,17 @@ def create_metadata(
         "buildRoles": [],
         "timeOfDayConstrainedReactions": []
     }
+    all_referenced_enum_names = []
+    all_referenced_function_names = []
     for ast_chunk in action_definitions + trope_definitions:
         # Compile all referenced enums
-        all_referenced_enum_names = set(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
-        metadata["referencedEnums"].extend(all_referenced_enum_names)
+        all_referenced_enum_names.extend(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
         # Compile all referenced adapter functions
-        all_referenced_function_names = set(
-            viv_compiler.utils.get_all_referenced_adapter_function_names(ast_chunk=ast_chunk)
-        )
-        metadata["referencedFunctionNames"].extend(all_referenced_function_names)
+        all_referenced_function_names.extend(viv_compiler.utils.get_all_referenced_adapter_function_names(
+            ast_chunk=ast_chunk
+        ))
+    metadata["referencedEnums"].extend(sorted(set(all_referenced_enum_names)))
+    metadata["referencedFunctionNames"].extend(sorted(set(all_referenced_function_names)))
     for action_definition in action_definitions:
         # Compile all roles carrying 'item' and 'build' labels
         for role_definition in action_definition["roles"].values():

viv_compiler/core/validation.py

@@ -20,7 +20,7 @@ from pydantic import TypeAdapter
 
 
 def validate_join_directives(raw_action_definitions: list[viv_compiler.types.RawActionDefinition]) -> None:
-    """Ensure that the given action definition makes proper use of `join` directives.
+    """Make sure that the given action definition makes proper use of `join` directives.
 
     If this validation check passes, the given action definitions are ready for inheritance to be handled.
 
@@ -65,10 +65,10 @@ def validate_preliminary_action_definitions(
         Exception: At least one action definition did not pass validation.
     """
     for action_definition in intermediate_action_definitions:
-        # Ensure that a 'roles' field is present
+        # Make sure that a 'roles' field is present
         if "roles" not in action_definition:
             raise KeyError(f"Action '{action_definition['name']}' is missing a 'roles' field, which is required")
-        # Ensure that there is a single initiator role. Note that during initial validation,
+        # Make sure that there is a single initiator role. Note that during initial validation,
         # the 'roles' field is still a list.
         _detect_wrong_number_of_initiators(action_definition=action_definition)
         # Detect duplicated role names
@@ -137,7 +137,9 @@ def _detect_reference_to_undefined_role(action_definition: viv_compiler.types.In
         Exception: The action definition did not pass validation.
     """
     # Retrieve the names of all defined roles ('roles' is still a list at this point in postprocessing)
-    all_defined_role_names = {role['name'] for role in action_definition['roles']} | {'hearer', 'this', 'default'}
+    all_defined_role_names = (
+        {role['name'] for role in action_definition['roles']} | viv_compiler.config.SPECIAL_ROLE_NAMES
+    )
     # Validate report references
     if action_definition["report"]:
         for reference in viv_compiler.utils.get_all_referenced_roles(action_definition["report"]):
@@ -243,11 +245,25 @@ def _validate_trope_definitions(trope_definitions: dict[str, viv_compiler.types.
         # Detect any reference to an undefined param
         all_referenced_params = viv_compiler.utils.get_all_referenced_roles(ast_chunk=trope_definition)
         for referenced_param in all_referenced_params:
-            if referenced_param not in trope_definition["params"]:
+            if referenced_param not in [trope_param["name"] for trope_param in trope_definition["params"]]:
                 raise KeyError(
                     f"Trope '{trope_definition['name']}' references undefined parameter: "
                     f"'{referenced_param}'"
                 )
+        # Detect assignments, which are not allowed in trope bodies
+        assignments_in_trope_body = viv_compiler.utils.get_all_expressions_of_type(
+            expression_type=ExpressionDiscriminator.ASSIGNMENT,
+            ast_chunk=trope_definition
+        )
+        if assignments_in_trope_body:
+            raise ValueError(f"Trope '{trope_definition['name']}' has assignment in body (not allowed)")
+        # Detect reactions, which are not allowed in trope bodies
+        reactions_in_trope_body = viv_compiler.utils.get_all_expressions_of_type(
+            expression_type=ExpressionDiscriminator.REACTION,
+            ast_chunk=trope_definition
+        )
+        if reactions_in_trope_body:
+            raise ValueError(f"Trope '{trope_definition['name']}' has reaction in body (not allowed)")
 
 
 def _validate_action_definitions(
@@ -279,7 +295,10 @@ def _validate_action_definitions(
         _validate_action_effects(action_definition=action_definition)
         # Validate reactions
         _validate_action_reactions(action_definition=action_definition, all_action_definitions=action_definitions)
+        # Validate saliences
+        _validate_action_saliences(action_definition=action_definition)
         # Validate associations
+        _validate_action_associations(action_definition=action_definition)
         # Validate trope-fit expressions
         _validate_action_trope_fit_expressions(
             action_definition=action_definition,
@@ -291,6 +310,8 @@ def _validate_action_definitions(
         _validate_action_loops(action_definition=action_definition)
         # Validate assignments
         _validate_action_assignments(action_definition=action_definition)
+        # Validate references to scratch variables
+        _validate_scratch_variable_references(action_definition=action_definition)
         # Validate negated expressions
         _validate_negated_expressions(action_definition=action_definition)
         # Validate chance expressions
@@ -330,13 +351,13 @@ def _validate_action_roles(action_definition: viv_compiler.types.ActionDefinitio
     """
     # Validate the initiator role
     _validate_action_initiator_role(action_definition=action_definition)
-    # Ensure all roles have proper 'min' and 'max' values
+    # Make sure all roles have proper 'min' and 'max' values
     _validate_action_role_min_and_max_values(action_definition=action_definition)
-    # Ensure all roles have proper 'chance' and 'mean' values
+    # Make sure all roles have proper 'chance' and 'mean' values
     _validate_action_role_chance_and_mean_values(action_definition=action_definition)
-    # Ensure all roles with binding pools have proper ones
+    # Make sure all roles with binding pools have proper ones
     _validate_action_role_pool_directives(action_definition=action_definition)
-    # Ensure that the 'precast' label is only used if this is a special action
+    # Make sure that the 'precast' label is only used if this is a special action
     _validate_action_role_precast_label_usages(action_definition=action_definition)
 
 
@@ -354,13 +375,13 @@ def _validate_action_initiator_role(action_definition: viv_compiler.types.Action
     """
     # Retrieve the definition for the action's initiator role
     initiator_role_definition = action_definition['initiator']
-    # Ensure that the initiator role has no pool directive
+    # Make sure that the initiator role has no pool directive
     if initiator_role_definition["pool"]:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with a pool directive, which is not allowed for initiator roles"
         )
-    # Ensure that the initiator role casts exactly one entity
+    # Make sure that the initiator role casts exactly one entity
     if initiator_role_definition['min'] != 1:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
@@ -371,13 +392,13 @@ def _validate_action_initiator_role(action_definition: viv_compiler.types.Action
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with max other than 1 (there must be a single initiator)"
         )
-    # Ensure that the initiator role has no specified binding mean
+    # Make sure that the initiator role has no specified binding mean
     if initiator_role_definition['mean'] is not None:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with declared casting mean (there must be a single initiator)"
         )
-    # Ensure that the initiator role has no specified binding chance
+    # Make sure that the initiator role has no specified binding chance
     if initiator_role_definition['chance'] is not None:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
@@ -479,7 +500,7 @@ def _validate_action_role_pool_directives(action_definition: viv_compiler.types.
                 f"Action '{action_definition['name']}' has role '{role_definition['name']}' "
                 f"that requires a pool declaration but does not have one"
             )
-        # Ensure that all pool directives reference at most one other (valid) role
+        # Make sure that all pool directives reference at most one other (valid) role
         if role_definition["pool"]:
             all_pool_references = viv_compiler.utils.get_all_referenced_roles(role_definition["pool"])
             if len(all_pool_references) > 1:
@@ -604,25 +625,21 @@ def _validate_action_reactions(
     Raises:
         Exception: The action definition did not pass validation.
     """
-    # Ensure that all reactions are housed in the proper fields
-    fields_to_check = (
-        ("preconditions", action_definition["preconditions"]),
-        ("scratch", action_definition["scratch"]),
-        ("effects", action_definition["effects"]),
-    )
-    for field_name, field_value in fields_to_check:
-        reactions_in_this_field = viv_compiler.utils.get_all_expressions_of_type(
-            expression_type="reaction",
-            ast_chunk=field_value
-        )
-        if reactions_in_this_field:
-            raise ValueError(
-                f"Action '{action_definition['name']}' has reaction in '{field_name}' field "
-                f"(only allowed in 'reactions' field)"
+    # Make sure that all reactions are housed in the proper fields
+    for field_name, field_value in action_definition.items():
+        if field_name not in viv_compiler.config.ACTION_FIELDS_PERMITTING_REACTIONS:
+            reactions_in_this_field = viv_compiler.utils.get_all_expressions_of_type(
+                expression_type=ExpressionDiscriminator.REACTION,
+                ast_chunk=field_value
             )
+            if reactions_in_this_field:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has reaction in '{field_name}' field "
+                    f"(only allowed in 'reactions' field)"
+                )
     # Collect all reactions
     all_reactions = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="reaction",
+        expression_type=ExpressionDiscriminator.REACTION,
         ast_chunk=action_definition['reactions']
     )
     # Validate each reaction in turn
@@ -640,7 +657,7 @@ def _validate_action_reactions(
         queued_action_initiator_role_name = queued_action_definition['initiator']['name']
         initiator_is_bound = False
         for binding in reaction['bindings']:
-            if binding['value']['role'] == queued_action_initiator_role_name:
+            if binding['role'] == queued_action_initiator_role_name:
                 initiator_is_bound = True
                 break
         if not initiator_is_bound:
@@ -651,12 +668,21 @@ def _validate_action_reactions(
         # Make sure the reaction references only roles defined in the queued actions
         all_queued_action_role_names = queued_action_definition['roles'].keys()
         for binding in reaction['bindings']:
-            bound_role_name = binding['value']['role']
+            bound_role_name = binding['role']
             if bound_role_name not in all_queued_action_role_names:
                 raise KeyError(
                     f"Action '{action_definition['name']}' has '{queued_action_name}' reaction that "
                     f"references a role that is undefined for '{queued_action_name}': '{bound_role_name}'"
                 )
+        # Make sure that no role appears multiple times in the bindings
+        roles_already_precast = set()
+        for bindings in reaction['bindings']:
+            if bindings['role'] in roles_already_precast:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has '{queued_action_name}' reaction that "
+                    f"includes role '{queued_action_initiator_role_name}' in bindings more than once"
+                )
+            roles_already_precast.add(bindings['role'])
         # Make sure the reaction precasts all 'precast' roles
         for role_object in queued_action_definition['roles'].values():
             if not role_object['precast']:
@@ -664,7 +690,7 @@ def _validate_action_reactions(
             precast_role_name = role_object['name']
             role_is_precast = False
             for binding in reaction['bindings']:
-                bound_role_name = binding['value']['role']
+                bound_role_name = binding['role']
                 if bound_role_name == precast_role_name:
                     role_is_precast = True
                     break
@@ -675,6 +701,50 @@ def _validate_action_reactions(
                 )
 
 
+def _validate_action_saliences(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's 'saliences' field.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    # Detect cases of a saliences variable shadowing the name of a role from the same action
+    all_role_names = viv_compiler.utils.get_all_role_names(action_definition=action_definition)
+    if action_definition['saliences']['variable']:
+        if action_definition['saliences']['variable']['name'] in all_role_names:
+            raise ValueError(
+                f"Action '{action_definition['name']}' has 'saliences' variable name that shadows role name "
+                f"'{action_definition['saliences']['variable']['name']}' (this is not allowed)"
+            )
+
+
+def _validate_action_associations(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's 'associations' field.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    # Detect cases of an associations variable shadowing the name of a role from the same action
+    all_role_names = viv_compiler.utils.get_all_role_names(action_definition=action_definition)
+    if action_definition['associations']['variable']:
+        if action_definition['associations']['variable']['name'] in all_role_names:
+            raise ValueError(
+                f"Action '{action_definition['name']}' has 'associations' variable name that shadows role name "
+                f"'{action_definition['associations']['variable']['name']}' (this is not allowed)"
+            )
+
+
 def _validate_action_trope_fit_expressions(
     action_definition: viv_compiler.types.ActionDefinition,
     trope_definitions: dict[str, TropeDefinition]
@@ -692,7 +762,7 @@ def _validate_action_trope_fit_expressions(
         Exception: The action definition did not pass validation.
     """
     all_trope_fit_expressions = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="tropeFitExpression",
+        expression_type=ExpressionDiscriminator.TROPE_FIT_EXPRESSION,
         ast_chunk=action_definition
     )
     for trope_fit_expression in all_trope_fit_expressions:
@@ -725,21 +795,32 @@ def _validate_action_role_unpackings(action_definition: viv_compiler.types.Actio
     Raises:
         Exception: The action definition did not pass validation.
     """
-    # Ensure all role unpackings unpack roles that can cast multiple entities
+    # Retrieve all unpacked role names
     all_unpacked_role_names = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="roleUnpacking",
+        expression_type=ExpressionDiscriminator.ROLE_UNPACKING,
         ast_chunk=action_definition
     )
     for unpacked_role_name in all_unpacked_role_names:
+        if unpacked_role_name in viv_compiler.config.SPECIAL_ROLE_NAMES:
+            raise ValueError(
+                f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
+                f"always bound to a single entity): '{unpacked_role_name}'"
+            )
+    # Make sure all role unpackings unpack roles that can cast multiple entities. Here, we'll also
+    # include all our special roles, since these are always singletons.
+    for unpacked_role_name in all_unpacked_role_names:
+        error_message = (
+            f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
+            f"always bound to a single entity): '{unpacked_role_name}'"
+        )
+        if unpacked_role_name in viv_compiler.config.SPECIAL_ROLE_NAMES:
+            raise ValueError(error_message)
         for role_definition in action_definition['roles'].values():
             if role_definition['name'] == unpacked_role_name:
                 if role_definition['min'] == role_definition['max'] == 1:
-                    raise ValueError(
-                        f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
-                        f"always bound to a single entity): '{unpacked_role_name}'"
-                    )
+                    raise ValueError(error_message)
                 break
-    # Ensure that all other references to roles that can cast multiple entities use role unpackings
+    # Make sure that all other references to roles that can cast multiple entities use role unpackings
     single_entity_role_references = viv_compiler.utils.get_all_referenced_roles(  # I.e., using the '@role' notation
         ast_chunk=action_definition,
         ignore_role_unpackings=True
@@ -769,7 +850,10 @@ def _validate_action_loops(action_definition: viv_compiler.types.ActionDefinitio
     Raises:
         Exception: The action definition did not pass validation.
     """
-    all_loops = viv_compiler.utils.get_all_expressions_of_type(expression_type="loop", ast_chunk=action_definition)
+    all_loops = viv_compiler.utils.get_all_expressions_of_type(
+        expression_type=ExpressionDiscriminator.LOOP,
+        ast_chunk=action_definition
+    )
     for loop in all_loops:
         # Detect attempts to loop over single-entity role references (i.e., ones using '@role' notation)
         if loop['iterable']['type'] == ExpressionDiscriminator.ENTITY_REFERENCE:
@@ -780,10 +864,10 @@ def _validate_action_loops(action_definition: viv_compiler.types.ActionDefinitio
                     f"role: '{role_name}' (perhaps use * instead of @)"
                 )
         # Detect cases of a loop variable shadowing the name of a role from the same action
-        if loop['variable'] in viv_compiler.utils.get_all_role_names(action_definition=action_definition):
+        if loop['variable']['name'] in viv_compiler.utils.get_all_role_names(action_definition=action_definition):
             raise ValueError(
                 f"Action '{action_definition['name']}' has loop with variable name that "
-                f"shadows role name '{loop['variable']}' (this is not allowed)"
+                f"shadows role name '{loop['variable']['name']}' (this is not allowed)"
             )
 
 
@@ -799,27 +883,48 @@ def _validate_action_assignments(action_definition: viv_compiler.types.ActionDef
     Raises:
         Exception: The action definition did not pass validation.
     """
+    # Make sure that all assignments are housed in the proper fields
+    for field_name, field_value in action_definition.items():
+        if field_name not in viv_compiler.config.ACTION_FIELDS_PERMITTING_ASSIGNMENTS:
+            assignments_in_field = viv_compiler.utils.get_all_expressions_of_type(
+                expression_type=ExpressionDiscriminator.ASSIGNMENT,
+                ast_chunk=field_value
+            )
+            if assignments_in_field:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has assignment in '{field_name}' field "
+                    f"(only allowed in {', '.join(viv_compiler.config.ACTION_FIELDS_PERMITTING_ASSIGNMENTS)})"
+                )
+    # Collect all assignments
     all_assignments = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="assignment",
+        expression_type=ExpressionDiscriminator.ASSIGNMENT,
         ast_chunk=action_definition
     )
+    # Validate each assignment in turn
     for assignment in all_assignments:
         anchor = assignment['left']['value']['anchor']
         path = assignment['left']['value']['path']
-        if assignment['left']['type'] == ExpressionDiscriminator.ENTITY_REFERENCE:
+        # Detect attempts to set a local variable. Note that we do allow assignments that are anchored
+        # in local variables and also have a path, since this enables the common pattern of looping
+        # over a role unpacking to execute effects for each entity cast in the group role.
+        if assignment['left']['value']['local'] and not path:
+            raise ValueError(
+                f"Assignment expression in action '{action_definition['name']}' sets local variable '{anchor}', "
+                f"but local variables can only be set in loops, 'saliences' headers, and 'associations' headers"
+            )
+        if anchor != viv_compiler.config.ACTION_SELF_REFERENCE_ROLE_NAME and anchor in action_definition['roles']:
             # Detect attempts to recast a role via assignment (not allowed)
             if not path:
                 raise ValueError(
                     f"Assignment expression in action '{action_definition['name']}' recasts "
                     f"role '{anchor}' (this is prohibited)"
                 )
-            # Detect attempts to set data on the "entity" associated with a symbol role
-            if anchor != "this":
-                if action_definition['roles'][anchor]['symbol']:
-                    raise ValueError(
-                        f"Assignment expression in action '{action_definition['name']}' has "
-                        f"symbol role on its left-hand side: '{anchor}'"
-                    )
+            # Detect attempts to set data on a complex symbol role (currently prohibited)
+            if action_definition['roles'][anchor]['symbol']:
+                raise ValueError(
+                    f"Assignment expression in action '{action_definition['name']}' has "
+                    f"symbol role on its left-hand side (this is currently prohibited): '{anchor}'"
+                )
         # Detect a trailing eval fail-safe marker, which is bizarre and probably an authoring error
         if path and path[-1].get('failSafe'):
             raise ValueError(
@@ -828,8 +933,11 @@ def _validate_action_assignments(action_definition: viv_compiler.types.ActionDef
             )
 
 
-def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
-    """Validate the given action definition's usage of chance expressions.
+def _validate_scratch_variable_references(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's references to scratch variables.
+
+    This procedure ensures that any scratch variable that is referenced is assigned *somewhere* in
+    the action definition, but it does not ensure that the variable is assigned before it's used.
 
     Args:
         action_definition: An action definition from a compiled content bundle.
@@ -840,16 +948,22 @@ def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDef
     Raises:
         Exception: The action definition did not pass validation.
     """
-    all_chance_expression_values = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="chanceExpression",
+    # Retrieve the names of all scratch variables that are set anywhere in the action definition
+    all_assigned_scratch_variable_names = set(viv_compiler.utils.get_all_assigned_scratch_variable_names(
         ast_chunk=action_definition
-    )
-    for chance_value in all_chance_expression_values:
-        if chance_value < 0.0 or chance_value > 1.0:
-            raise ValueError(
-                f"Chance expression in action '{action_definition['name']}' has "
-                f"chance value outside of the range [0, 1]: '{chance_value * 100}%'"
-            )
+    ))
+    # Retrieve the names of all scratch variables that are referenced anywhere in the action definition
+    all_referenced_scratch_variable_names = set(viv_compiler.utils.get_all_referenced_scratch_variable_names(
+        ast_chunk=action_definition
+    ))
+    # Flag any cases of a scratch variable being referenced without being assigned anywhere
+    referenced_but_not_assigned = all_referenced_scratch_variable_names - all_assigned_scratch_variable_names
+    if referenced_but_not_assigned:
+        snippet = "'" + "', '".join(sorted(referenced_but_not_assigned)) + "'"
+        raise ValueError(
+            f"Action '{action_definition['name']}' references the following scratch variables without ever "
+            f"assigning them: {snippet}"
+        )
 
 
 def _validate_negated_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
@@ -873,6 +987,30 @@ def _validate_negated_expressions(action_definition: viv_compiler.types.ActionDe
             )
 
 
+def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's usage of chance expressions.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    all_chance_expression_values = viv_compiler.utils.get_all_expressions_of_type(
+        expression_type=ExpressionDiscriminator.CHANCE_EXPRESSION,
+        ast_chunk=action_definition
+    )
+    for chance_value in all_chance_expression_values:
+        if chance_value < 0.0 or chance_value > 1.0:
+            raise ValueError(
+                f"Chance expression in action '{action_definition['name']}' has "
+                f"chance value outside of the range [0, 1]: '{chance_value * 100}%'"
+            )
+
+
 def _validate_compiled_content_bundle_against_schema(content_bundle: viv_compiler.types.CompiledContentBundle) -> None:
     """Validate a compiled content bundle against its public schema.