ASL SEMANTIC VALIDATION RULES

This document lists semantic/linking validation behavior currently enforced OUTSIDE pure grammar structure for ASL.
Use this as a generation-time checklist so produced specifications are valid in the current language server implementation.

Scope of this file:
- Includes only rules that are relevant to authoring ASL specifications.
- Includes only rules that are actually enforced by current code (scope/linking behavior).
- Excludes hypothetical/domain rules that are not implemented.

Severity legend
- Error = unresolved/invalid reference in current scoping model
- Info = authoring guidance to avoid unresolved references

==================================================
ERRORS (must fix)
==================================================

1) All references must resolve
Rule: Any cross-reference must resolve to an existing symbol visible in scope.
Typical failures:
- Referencing unknown IDs/qualified names
- Referencing symbols not imported/visible
Effect: Linking error.

2) `Include ... fromSystem ... element ...` type must match
Rule: In `IncludeElement`, `element` must be a system concept whose runtime type matches the selected include type.
Allowed include types in grammar:
- UseCase, Actor, DataEntity, DataEntityCluster, DataEnumeration, ActiveEvent, ActiveTask, ActiveFlow
Example violation:
Include Actor fromSystem S1 element uc_Login
(uc_Login is a UseCase, not an Actor)
Effect: `element` cannot resolve in scoped candidates.

3) `Include ... fromSystem ... element ...` element must belong to selected source system
Rule: Included `element` is scoped to concepts declared in the specified `fromSystem` only.
Example violation:
Include DataEntity fromSystem S1 element e_FromS2
Effect: unresolved `element`.

4) Include source system cannot come from same document scope context
Rule: In include contexts, symbols from the same document are filtered out for reference resolution.
Practical effect: `fromSystem` is expected from external scope (typically imported/other document), not local same-file symbols.
Effect: unresolved reference when trying to include from local same-document declarations.

5) Data table header attributes must belong to the Data type entity
Rule: Inside `Data ... := [[header...][rows...]]`, header attribute refs are scoped to attributes of the `Data` target entity.
Example violation:
Data d1 : e_Order := [
  [customerName]   // customerName not attribute of e_Order
]
Effect: unresolved header attribute.

6) `extends ... onExtensionPoint ...` must reference extension points of the selected base use case
Rule: In `UCExtends`, `extensionPoint` candidates are filtered to those owned by the referenced `usecase`.
Example violation:
extends uc_A onExtensionPoint ep_FromOtherUseCase
Effect: unresolved `extensionPoint`.

7) View reference type restrictions by selected ViewType
Rule: For `View ... : <ViewType> [ references... ]`, scope provider restricts valid reference categories:
- UseCaseView -> UseCase elements
- ActiveStructureView -> ActiveStructure elements
- ActiveView -> Active elements
- PassiveStructureView -> PassiveStructure elements
- UIView -> UI elements
Example violation:
View v1 : UseCaseView [ e_Order ]
Effect: unresolved `references` entry due to filtered scope.

==================================================
INFO (authoring guidance that follows current scoping behavior)
==================================================

8) Import visibility controls what can be referenced globally
Rule: Global candidates are normalized/filtered through import matching behavior.
- Explicit import: `Import a.b.C` exposes `C`-style name mapping for that symbol.
- Wildcard import: `Import a.b.*` exposes symbols under that namespace.
If not imported (or otherwise in allowed global scope), references may fail to resolve.

9) Prefer unqualified names for `System` references in many contexts
Rule: Scope provider applies single-segment filtering for certain reference types (notably `System`, and `State` if present in model variants).
Guidance: use simple IDs where those refs are expected, unless your environment customizes this behavior.

==================================================
NOT ENFORCED CURRENTLY (but should be validated in generation)
==================================================

The following semantic policies are NOT currently implemented as active checks in the ASL plugin,
but SHOULD be enforced during LLM generation to produce valid specifications.

10) Reserved Words
Rule: Cannot use reserved words as element identifiers (name/ID).
Reserved words include:
- Core keywords: Package, Import, System, IncludeAll, Include, View, Theme
- System concepts: Actor, DataEntity, DataEntityCluster, DataEnumeration, Data, UseCase, Context, ContextVariable
- Behavior: Event, Task, TaskFlow
- UI: UIContainer, UIComponent, UIComponentPart, UIAction, UIPortDefinition, UIEvent, UIParameter, UIExpression
- Type extensions: SystemType, SystemSubType, MetricType, ActorType, ActiveEventType, ActiveTaskType, ActiveFlowType, UseCaseType, ActionType, DataEntityType, DataEntitySubType, DataEntityClusterType, DataAttributeType, ForeignKeyOnDeleteType, UIContainerType, UIContainerSubType, UIComponentType, UIComponentSubType, UIWireframeType, UIComponentPartType, UIComponentPartSubType, UIActionType, UIPortDefinitionType, UIThrowingEventType, UISystemEventType, UIActionEventType, UIElementEventType, UIElementEventSubType, ContextDimensionDeviceType, ScreenSizeCategoryType, NetworkConnectivityType, ContextDimensionSensorType, SensorStatusType, StereotypeType
- Data types: Integer, Double, Decimal, Boolean, Bit, Currency, Date, Time, Datetime, String, Text, Regex, URL, Email, File, Image, XML, Binary, FilePath
- Literals: True, False, Other
- Built-in actions: aCreate, aRead, aUpdate, aDelete
- Other keywords: stereotype, component, part, action, event, throwingEvent, uiPortDefinition, attribute, formula, arithmetic, details, constraints, values, isFinal, isReusable, isTestSuite, systemUnderTest, partOf, vendor, version, tag, description
Solution: Use lowercase or alternate naming (e.g., `actor_user` instead of `Actor`, `data_attribute` instead of `DataAttribute`).

11) Unique IDs within System
Rule: Every SystemConcept ID must be unique within its containing System.
Applies to: All elements declared inside a System (Actor, DataEntity, DataEntityCluster, DataEnumeration, Data, UseCase, Event, Task, TaskFlow, Context, ContextVariable, UIContainer, UIComponent, etc., View, Theme, stereotype, type extensions).
Example violation:
System MySystem : Application
    Actor a_User : User
    Actor a_User : User  // ERROR: duplicate ID
Solution: Use unique IDs or add distinguishing suffixes: a_User, a_User_2, a_User_Admin.

12) Type/Subtype Consistency
Rule: When both type and subtype are specified, the subtype must be a valid subtype of the type.
Applies to: System, DataEntity, UIContainer, UIComponent, UIComponentPart, UIElementEvent
Example violations:
System s1 : Application:HardwareSystem_Server  
// ERROR: HardwareSystem_Server is not an Application subtype

DataEntity e1 : Master:Fact  
// ERROR: Fact is not a Master subtype (Fact is Multidimensional subtype)

UIContainer ui1 : Window:Menu_Main
// ERROR: Menu_Main is not a Window subtype

Valid type-subtype combinations (from grammar):
- System:
  * Business: Business_PublicSector, Business_IT, Business_Other
  * Application: Application_Web, Application_Mobile, Application_Desktop, Application_Sensor, Application_Actuator, Application_Other
  * SoftwareSystem: SoftwareSystem_OS, SoftwareSystem_VM, SoftwareSystem_DBMS, SoftwareSystem_WebServer, SoftwareSystem_WebClient, SoftwareSystem_EmailServer, SoftwareSystem_EmailClient, SoftwareSystem_OfficeTool, SoftwareSystem_OtherServer, SoftwareSystem_OtherClient, SoftwareSystem_Other
  * HardwareSystem: HardwareSystem_Server, HardwareSystem_Desktop, HardwareSystem_Laptop, HardwareSystem_Smartphone, HardwareSystem_Smartwatch, HardwareSystem_Sensor, HardwareSystem_Actuator, HardwareSystem_Storage, HardwareSystem_Printer, HardwareSystem_Network, HardwareSystem_Other
  * Other: (no predefined subtypes)

- DataEntity:
  * Parameter, Reference, Document, Transaction, Other: Regular, Weak, Other
  * Master: Regular, Weak, Other
  * Multidimensional: Fact, Dimension, Other

- UIContainer:
  * Window: Window_Modal, Window_Modeless
  * Menu: Menu_Main, Menu_Contextual
  * Other: Other

- UIComponent:
  * List: List_MultiChoice, List_Tree, List_Table, List_Nested
  * Form: Form_Simple, Form_MasterDetail, Form_Other
  * Dialog: Dialog_Success, Dialog_Error, Dialog_Warning, Dialog_Info, Dialog_Message
  * Menu: Menu_Main, Menu_Contextual
  * Details, Other: Other

- UIComponentPart:
  * Field: Field_Output, Field_Input, Field_Selection, Field_EditableSelection
  * Slot: Slot_MenuGroup, Slot_MenuOption, Slot_MenuSeparator, Slot_Other
  * Other: Other

- UIElementEvent:
  * Submit: Submit_Create, Submit_Read, Submit_Update, Submit_Delete, Submit_Up, Submit_Back, Submit_Ok, Submit_Cancel
  * Select, Other: Other

13) TaskFlow Condition constraint
Rule: `condition` property is only allowed when TaskFlow type is `SequenceConditional`.
Example violation:
TaskFlow tf1 : Sequence [
    condition "x > 0"  // ERROR: Sequence cannot have condition
    activeElements ev1, t1
]

TaskFlow tf2 : Parallel [
    condition "y == true"  // ERROR: Parallel cannot have condition
    activeElements t2, t3
]
Valid usage:
TaskFlow tf3 : SequenceConditional [
    condition "status == Active"  // OK
    activeElements ev1, t1
]

14) Task Participant constraints
Rule: `partOf` property specifies hierarchical relationships and is optional.
Note: Unlike RSL's ActiveTask with strict participant rules for Send/Receive, ASL Task grammar does not define participantExternal in the grammar for Task. If added later, similar constraints would apply.

15) UseCase Self-Extension
Rule: A UseCase cannot extend itself.
Example violation:
UseCase uc1 : EntityCreate [
    actorInitiates a_User
    extends uc1 onExtensionPoint ep1  // ERROR: cannot extend itself
]
Solution: Extend a different use case or remove the extends relationship.

16) Hierarchy Cycles
Rule: No cycles allowed in hierarchical relationships.
Applies to:
- `isA`: Actor (ContextDimensionActor), DataEntity
- `partOf`: Task

Example violations:
Actor a1 : User [
    isA a2
]
Actor a2 : User [
    isA a1  // ERROR: cycle in isA hierarchy
]

DataEntity e1 : Master [
    isA e2
]
DataEntity e2 : Master [
    isA e1  // ERROR: cycle
]

Task t1 : User [
    partOf mandatory t2
]
Task t2 : Service [
    partOf optional t1  // ERROR: cycle in partOf hierarchy
]

Solution: Break the cycle by reordering or removing one relationship.

17) System isTestSuite constraint
Rule: When `isTestSuite` is true, `systemUnderTest` must reference another System.
Example violation:
System TestSys : Application [
    isTestSuite  // ERROR: missing systemUnderTest reference
]
Valid usage:
System ProductionSys : Application
System TestSys : Application [
    isTestSuite
    systemUnderTest ProductionSys  // OK
]

18) DataEntity constraints combinations
Rule: Entity-level constraint `showAs(...)` must reference an attribute of that entity.
Example violation:
DataEntity e_Order : Transaction [
    attribute orderId : Integer
    constraints(showAs(customerName))  // ERROR: customerName not an attribute of e_Order
]

19) DataAttribute ForeignKey constraint references
Rule: ForeignKey must reference an existing DataEntity.
Optional fields (toField, showAsField) must reference attributes of the target entity.
Example violation:
DataEntity e_Customer : Master [
    attribute id_ : Integer
]
DataEntity e_Order : Transaction [
    attribute customerId : Integer [
        constraints(ForeignKey(e_NonExistent toField id_))  // ERROR: e_NonExistent doesn't exist
    ]
]

20) DataAttribute ManyToMany constraint references
Rule: ManyToMany must reference valid entities and their attributes.
Example violation:
DataEntity e_Order : Transaction [
    attribute products : Integer [
        constraints(ManyToMany(e_Product throughEntity e_Missing))  // ERROR: e_Missing doesn't exist
    ]
]

21) DataEnumerationRef in attribute type
Rule: When an attribute uses `DataEnumeration <ref>`, the referenced enumeration must exist.
Example violation:
DataEntity e_Order : Transaction [
    attribute status_ : DataEnumeration enum_NonExistent  // ERROR: enum_NonExistent not defined
]

22) UIComponent recursiveNestedDataBinding and dataFlowTo constraints
Rule: `recursiveNestedDataBinding` and `dataFlowTo` must reference valid entities/components respectively.
Example violation:
component cmp1 : List [
    dataFlowTo cmp_NonExistent  // ERROR: cmp_NonExistent doesn't exist
]

23) Context dimension references
Rule: Context must reference valid Actor (ContextDimensionActor), ContexDevice, and ContexSensor elements.
Example violation:
Context c1 [
    actor a_NonExistent  // ERROR: actor must reference valid ContextDimensionActor
]

==================================================
LLM GENERATION RECOMMENDATIONS
==================================================

When generating ASL specifications, validation prompts should require:

MUST enforce (linking errors):
1. Define all symbols before use or import them properly
2. Align Include element types with Include type declaration
3. Match View references to selected ViewType
4. Use extension points from the exact referenced use case in UCExtends
5. Reference only attributes of the correct entity in Data table headers
6. Ensure all cross-references resolve within scope

SHOULD enforce (semantic correctness, not currently validated by code):
7. Avoid reserved words as identifiers
8. Use unique IDs within each System
9. Match type/subtype combinations to grammar-defined valid pairs
10. Add `condition` only to SequenceConditional TaskFlow
11. Prevent UseCase self-extension
12. Avoid cycles in isA and partOf hierarchies
13. Include `systemUnderTest` when using `isTestSuite`
14. Validate constraint references (showAs, ForeignKey, ManyToMany, etc.)
15. Ensure DataEnumeration references exist
16. Validate UI dataFlowTo and recursiveNestedDataBinding references
17. Validate Context dimension references

PROMPT TEMPLATE ADDITION:
"Follow all ASL semantic validation rules. Specifically:
- Never use ASL reserved words as identifiers
- Ensure all IDs are unique within their System
- Match type/subtype pairs to valid grammar combinations  
- Only add 'condition' to SequenceConditional TaskFlow
- Never create cycles in isA or partOf hierarchies
- Never make a UseCase extend itself
- Always define symbols before referencing them"