docs(timeline): explain the per-interval tick schedule (#1130)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tcoratger

src/lean_spec/spec/forks/lstar/timeline.py

@@ -19,7 +19,24 @@ def tick_interval(
         has_proposal: bool,
         is_aggregator: bool = False,
     ) -> tuple[LstarStore, list[SignedAggregatedAttestation]]:
-        """Advance store time by one interval and perform interval-specific actions."""
+        """
+        Advance store time by one interval and perform interval-specific actions.
+
+        Each slot is split into five intervals so consensus work runs at fixed points
+        relative to when a block arrives and votes spread across the network.
+
+        Timing of the action points within a slot:
+
+        - Interval 0: ingest the slot's pending votes once the proposal has landed.
+        - Interval 2: aggregators bundle the slot's votes into proofs and broadcast them.
+        - Interval 3: advance the safe target from the latest votes for fast confirmation.
+        - Interval 4: ingest the votes that accumulated through the rest of the slot.
+
+        Aggregation waits until interval 2 so a block proposed at the slot start has
+        time to propagate and gather votes before they are bundled.
+        Fast confirmation sits at interval 3, after aggregates exist, so the safe
+        target reflects the freshest votes the node has seen.
+        """
         store = store.model_copy(update={"time": store.time + Interval(1)})
         interval_within_slot = int(store.time) % int(INTERVALS_PER_SLOT)
         new_aggregates: list[SignedAggregatedAttestation] = []