add more notes

Author: multun

content/docs/reference/design-docs/running-time-calculation/_index.en.md

@@ -137,8 +137,51 @@ SimResults[simulation result curve]
 ## Driving instructions
 
 Driving instructions model what the train has to do, and under what conditions.
-It's a high-level primitive: an abstract order, not a curve.
+Driving instructions are generated using domain constraints such as:
 
+- unsignaled line speed limits
+- permanent signaled speed limits
+- temporary speed limits
+- dynamic signaling:
+  - block / moving block
+  - dynamically signaled speed restrictions
+- neutral zones
+- stops
+
+
+There are two types of driving instructions:
+
+- **Abstract driving instructions** model the high-level, rolling stock independant
+range of acceptable behavior: reach 30km/h at this location
+- **Concrete driving instructions** model the specific range of acceptable behavior
+for a specific rolling stock: follow this breaking curve and maintain 30km/h.
+
+```mermaid
+flowchart TD
+Constraint[constraint]
+AbstractDrivingInstruction[abstract driving instruction]
+ConcreteDrivingInstruction[concrete driving instruction]
+RollingStockIntegrator[rolling stock integrator]
+Compiler([compiler])
+
+Constraint -- generates one or more --> AbstractDrivingInstruction
+AbstractDrivingInstruction --> Compiler
+RollingStockIntegrator --> Compiler
+Compiler --> ConcreteDrivingInstruction
+```
+
+
+### Interpreting driving instructions
+
+During the simulation, driving instructions are partitionned into 4 sets:
+
+- `PENDING` instructions may apply at some point in the future
+- `RECEIVED` instructions aren't enforced yet, but will be unless overriden
+- `ENFORCED` instructions influence train behavior
+- `DISABLED` instructions don't ever have to be considered anymore. There are multiple ways instructions can be disabled:
+  - `SKIPPED` instructions were not received
+  - `RETIRED` instructions expired by themselves
+  - `OVERRIDEN` instructions were removed by another instruction
 
 ```mermaid
 flowchart TD
@@ -149,6 +192,11 @@ subgraph disabled
     overriden
 end
 
+subgraph active
+    received
+    enforced
+end
+
 pending --> received
 pending --> skipped
 received --> enforced
@@ -157,10 +205,39 @@ enforced --> retired
 enforced --> overriden
 ```
 
+These sets evolve as follows:
 
-```rust
+- when an integration steps overlaps a `PENDING` instruction's received condition, it is `RECEIVED` and becomes a candidate to execution
+  - existing instructions may be `OVERRIDEN` due to an `override_on_received` operation
+- if an instruction cannot ever be received at any future simulation state, it transitions to the `SKIPPED` state
+- when simulation state exceeds an instruction's enforcement position, it becomes `ENFORCED`. Only enforced instructions influence train behavior.
+  - existing instructions may be `OVERRIDEN` due to an `override_on_enforced` operation
+- when simulation state exceeds an instruction's retirement position, it becomes `RETIRED`
 
 
+### Overrides
+
+When an instruction transitions to the `RECEIVED` or `ENFORCED` state, it can disable active instructions
+which match some metadata predicate. There are two metadata attributes which can be relied on for overrides:
+
+- the `kind` allows overriding previous instructions for a given domain, such as spacing or block signaled speed limits
+- the `rank` can be used as a "freshness" or "priority" field. If two instructions overriding each other are received
+  (such as when a train sees two signals), the rank allows deciding which instruction should be prioritized.
+
+This is required to implement a number of signaling features, as well as stops, where the stop instruction is overriden
+by the restart instruction.
+
+
+### Data model
+
+
+
+```rust
+struct ReceivedCond {
+    position_in: Option<PosRange>,
+    time_in: Option<TimeRange>,
+}
+
 struct InstructionMetadata {
     // state transitions
     received_when: ReceivedCond,
@@ -181,7 +258,6 @@ struct InstructionMetadata {
 enum AbstractInstruction {
     NeutralZone,
     SpeedTarget {
-        enforcement: Enforcement,
         at: Position,
         speed: Speed,
     }
@@ -190,16 +266,10 @@ enum AbstractInstruction {
 enum ConcreteInstruction {
     NeutralZone,
     SpeedTarget {
-        enforcement: Enforcement,
         braking_curve: SpeedPosCurve,
     },
 }
 
-struct ReceivedCond {
-    position_in: Option<PosRange>,
-    time_in: Option<TimeRange>,
-}
-
 struct OverrideFilter {
     kind: InstructionKindId,
     rank: Option<(RankRelation, usize)>,
@@ -213,7 +283,65 @@ enum RankRelation {
 
 # Design decisions
 
-## Driving instruction overrides
+## Lowering constraints to an intermediate representation
+
+Early on, we started making lists of what domain constraints can have an impact on train behavior.
+Meanwhile, to simulate train behavior, we figured out that we need to know which constraints apply at any given time.
+
+There's a fundamental tension between these two design constraints, which can be resolved in one of two ways:
+
+- either treat each type of constraint as its own thing during the simulation
+- abstract away constraints into a common representation, and then simulate that
+
+### {{< rejected >}} Distinct constraint types
+
+When we first started drafting architecture diagrams, the train simulation API directly took
+a bunch of constraint types as an input. It brought up a number of issues:
+
+- the high diversity of constraint types makes it almost impossible to describe all interactions between all constraint types
+- the domain of some of these interactions is very complex (block signaling)
+- when simulating, it does not seem to matter why a constraint is there, only what to do about it
+
+We couldn't find clear benefits to dragging distinctions between constraint types deep into the implementation
+
+### {{< rejected >}} Internal constraint types abstraction
+
+We then realized that abstracting over constraint types during simulation had immense benefits:
+
+- it allows expressing requirements on what constraints need to be enforceable
+- it greatly simplifies the process of validating constraint semantics: instead of having to validate interactions between
+  every possible type of constraints, we only have to validate that constraint semantics can be expressed by the abstract
+  constraint type
+
+We decided the explore the possibility of keeping constraint types distinct in the external API, but lowering these constraints into an intermediary representation internaly. We found a number of downsides:
+
+- the public simulation API would still bear the complexity of dealing with many constraint types
+- there would be a need to incrementaly generate internal abstracted constraints to support the incremental API
+
+### {{< adopted >}} External constraint types abstraction
+
+We tried to improve over the previous proposal by moving the burden of converting many constraints into a common abstraction out of the simulation API. We found that doing so:
+
+- reduces the API surface of the train simulation module
+- decouples behavior from constraint types: if a new constraint type needs to be added, the simulation
+  API only needs expansion if the expected behavior expected for this constraint isn't part of the API.
+
+
+## Interpreting driving instructions
+
+As the train progresses through the simulation, it reacts according to driving instructions
+which depend on more than the bare train physics state (position, time, and speed):
+
+- the behavior of a train on each block depends on the state of the last passed block signal
+- when a train stops at a red signal, then restarts, it may have to keep applying the driving
+  instruction from the previous signal until the formerly red light is passed
+
+Thus, given:
+
+- set of all possible driving instructions (alongside applicability metadata)
+- the result of previous integration steps (which may be extended to hold metadata)
+
+There is a need to know what driving instructions are applicable to the current integration step.
 
 Overrides are a way of modelling instructions which disable previous ones. Here are some examples:
 
@@ -227,6 +355,6 @@ We identified multiple filtering needs:
 
 We quickly settled on adding a kind field, but had a lengthy discussion over how to discriminate upstream and downstream signals. We explored the following options:
 
-- adding `source` metadata, which was rejected as it does not address the issue of upstream / downstream
-- adding identifiers to instructions, and overriding specific instructions, which was rejected as it makes instruction generation and processing more complex
-- adding some kind of priority / rank field, which was adopted
+- {{< rejected >}} adding `source` metadata, which was rejected as it does not address the issue of upstream / downstream
+- {{< rejected >}} adding identifiers to instructions, and overriding specific instructions, which was rejected as it makes instruction generation and processing more complex
+- {{< adopted >}} adding some kind of priority / rank field, which was adopted