MPIDE-25: document interaction update

Interactions have been clarified and further refined. Documentation has
been added for their new planned implementation, as well as for code
blocks and init statements.

docs/overview.md

@@ -8,7 +8,7 @@ SYSTEM: task_b = receive*;
 INTERACTION: task_a:send -> task_b:receive;
 ```
 
-`modellang` is not just an ergonomic language, though. Its **trace generator** is able to simulate all possible scenarios of a model within a small scope, producing a queryable set of results.
+`modellang` is not just an ergonomic language, though. Its **trace generator** is able to simulate all possible scenarios of a model within a small scope, producing a queryable set of results (known as event traces).
 
 ## language
 A `modellang` model is composed of systems of behaviors, interactions between the systems, and triggers that control properties.
@@ -20,17 +20,19 @@ SYSTEM: sys = behavior_pattern atomic_event;
 BEHAVIOR: behavior_pattern = expanded detail;
 ```
 
-An **interaction** can fall into one of three categories: relations. pre-conditions, and post-conditions:
-- the two relations supported are "->" (order) and "==" (join)
-- pre- and post-conditions guarantee your resultant traces abide by certain rules
-- an interaction is a condition iff one operand of the "->" is an expression and the other is a selector; two selector operands makes for a relation; and two expressions makes for an invalid interaction
+An **interaction** defines a relation between two or more systems, and optionally enforce conditional requirements:
+- the two relations supported are:
+  - `a -> b` (**then**) - orders events such that the traces will always result in a, then b
+  - `a == b` (**join**) - joins systems together in the traces by treating a and b as the same event
+- conditions can be attached by including a `{ code block }` before or after a selector
+  - `{ /* condition */ } system:thing` (**pre**) - executes before the event; if it returns false, the event is not inserted
+  - `system:thing { /* condition */ }` (**post**) - executes after the event and its triggers; if it returns false, the event is removed and the branch is pruned
 - selectors (also found in triggers) are patterns just like system and behavior definitions, but come with a prepended `system:` to inform the generator where to look for the pattern
 
 ```
 INTERACTION: sys:before -> other_sys:after;
 INTERACTION: sys:shared_event == other_sys:shared_event;
-INTERACTION: property > 5 -> thing:happens_only_above_5;
-INTERACTION: thing:never_drops_below_three -> other_property >= 3;
+INTERACTION: { property > 5 } thing:happens_above_5 -> other_thing:stays_above_two { other_property >= 3 };
 ```
 
 A **trigger** is a chunk of code that will execute whenever the specified selector pattern occurs during trace generation.
@@ -47,7 +49,28 @@ SYSTEM: group = you can even (wrap stuff into groups);
 SYSTEM: alternation = a (pipe | vertical bar | stick) delimited list of sequences;
 BEHAVIOR: quantifiers = none_or_more* one_or_more+ none_or_one?;
 BEHAVIOR: ranges = do_exactly_n_times{n} do_at_least_n_times{n,} do_n_to_m{n,m};
-```  
+```
+
+An **init** establishes the initial state of the model or a system through a code block.
+
+```
+INIT: { initial_property = 5 };
+INIT: system_a { SYSTEM.initial_property = 9001 };
+```
 
 **Whitespace** is insignificant.  
 **Comments** are C-style.
+
+## code blocks
+In their current form, the code blocks found in `modellang` are embedded JavaScript. They have access to different variables depending on what construct they are being used in.
+
+**Conditionals** are lambdas that do not have access to any special scope except `MODEL`  
+**Inits** have access to `MODEL`, and `SYSTEM` if a system is specified  
+**Triggers** have access to `MODEL`, `SYSTEM`, `PREVIOUS`, `THIS`  
+
+```
+MODEL: contains information about the systems in the model
+SYSTEM: contains information about the events in the current system
+PREVIOUS: a reference to the previous node in the event trace
+THIS: a reference to the current node in the event trace
+```