Added concepts for seasonal, conditional ratings

docs/Gemfile.lock

@@ -270,7 +270,7 @@ GEM
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.8.0)
     uri (0.13.1)
-    webrick (1.8.1)
+    webrick (1.8.2)
 
 PLATFORMS
   x86_64-linux

docs/concepts.md

@@ -174,6 +174,24 @@ a distinct data set from Proposals. Proposals may be queried as well as
 submitted, so that the rating provider's original input data is always kept
 separately from the in-use ratings.
 
+## Seasonal Ratings
+
+Seasonal Line Ratings, or simply Seasonal Ratings in TROLIE, are based on the 
+formal definition in the pro forma attachment M of FERC order 881, which states:
+
+> (3) "Seasonal Line Rating" means a Transmission Line Rating that:
+
+> (a) Applies to a specified season, where seasons are defined by the Transmission Provider to include not fewer than four seasons in each year, and to reasonably reflect portions of the year where expected high temperatures are relatively consistent.
+
+> (b) Reflects an up-to-date forecast of ambient air temperature across the relevant season over which the rating applies.
+
+> (c) Is calculated annually, if not more frequently, for each season in the future for which Transmission Service can be requested.
+
+Seasonal ratings are used as [Recourse Ratings](#recourse-ratings) in a TROLIE context, as described above.  They also may be used for other purposes that go beyond the AAR timeline, 
+such as planning and other long-term studies.  
+
+Seasonal Ratings are defined against [Seasons](#seasons).  
+
 ## Seasonal Overrides
 
 A seasonal override is submitted by a Ratings Provider in order to instruct the
@@ -222,3 +240,17 @@ Another typical Monitoring Set would be that which nominates the complete
 footprint for the Transmission Provider. A natural choice for the
 `monitoring-set` identifier is the NERC id of the entity that defines the
 `monitoring-set`, if applicable.
+
+## Seasons
+
+According to pro forma attachment M of FERC 881, a season has the following definition:
+
+> ... where seasons are defined by the Transmission Provider to include not fewer than four seasons in each year, and to reasonably reflect portions of the year where expected high temperatures are relatively consistent.
+
+In practical terms, Transmission Providers have a wide variety of Seasons that they operate to.  
+Even if seasons across two Transmission Providers have the same name, such as "summer", 
+the start and end dates may differ.  TROLIE is designed to be agnostic to these definitions as much as
+possible, so that the data may be exchanged in a more accurate and precise manner.  While seasonal "aliases"
+such as "winter" may sometimes be provided as hints, seasonal rating schedules are ultimately defined in terms 
+of start and end dates.  Seasonal ratings in TROLIE are represented in terms of start and end dates, and 
+TROLIE servers may decide how to enforce adherence to specific named seasons that they use.  

docs/decision-log/conditional-ratings.md

@@ -0,0 +1,50 @@
+---
+title: Conditional Seasonal Ratings
+parent: Decision Records
+---
+
+## Status
+
+* Status: `accepted`
+* Issue Link: [GitHub Issue](https://github.com/trolie/spec/issues/129)
+
+## Context
+
+There are certain transmission lines that can have different ratings depending on their 
+configuration. A commonly cited example is underwater lines with cables packed tightly in 
+trays, where certain combinations of the conductors may be turned on and off. Switching 
+conductors on and off obviously changes the amount of copper that can carry 
+electrons. However, to add additional complexity, the wires are close enough together
+that they can heat each other up as well, and the overall rating must take this into 
+account. Therefore, each possible combination will have a unique rating.
+
+When computing AARs however, it is necessary to take the configuration into account
+so that the AAR accounts for the actual or forecasted configuration of the line.  Therefore,
+no special accommodation needs to be considered for AAR exchange in TROLIE.  
+
+However, for seasonal ratings, the configuration of the line cannot be 
+forecasted accurately for use as a recourse rating. A separate rating must be 
+provided for each configuration, so that the right rating may be used based on the 
+configuration of the line.  
+
+This decision records a strategy for these "conditional" ratings in TROLIE.  
+
+## Decision
+
+TROLIE will contain no specific schema elements to represent conditional ratings.
+For lines that require conditional ratings, TROLIE servers must expose unique
+resource identifiers representing each condition / permutation of the configuration. 
+
+This follows from the similar precedent set by the decision 
+for [directional ratings](directional-ratings.md).
+
+### Conditional-Resource Naming
+Much like the problem in naming directional ratings, there is currently no consistent 
+approach as to how these "conditions" are represented.  TROLIE implementations will
+be left on their own to implement a convention for these names, likely concatenating
+the facility ID with an ID for each possible condition.  
+
+
+## Consequences
+
+An example is provided in [the seasonal ratings examples](../example-narratives/seasonal-ratings.md).

docs/decision-log/seasonal-ratings-schedule.md

@@ -0,0 +1,81 @@
+---
+title: Seasonal Ratings
+parent: Decision Records
+---
+
+## Status
+
+* Status: `accepted`
+* Issue Link: [GitHub Issue](https://github.com/trolie/spec/issues/14)
+
+## Context
+
+While the primary focus of FERC 881 is AARs, the [seasonal ratings](../concepts.md#seasonal-ratings) 
+still play an important role.  In practice, these are used in planning and other non-operational studies
+in addition to their role as recourse ratings in operations.  
+
+Today, seasonal ratings are managed using various tools, and often tied to network model update processes.  For various
+reasons, many of these tools and processes will need to continue to be supported as they are today.  However, 
+FERC 881 creates a practical need to be able to share these ratings in a more structured way, implying that
+some support for seasonal ratings makes sense in TROLIE, even if it is optional.  
+
+However seasonal rating interop is challenging, because the definition and meaning of each season differs 
+between grid operators.  The definition for [seasons](../concepts.md#seasons) in the FERC 881 context is
+quite flexible.  While internally, grid operators may assign seasonal ratings to well-known named seasons 
+such as `Fall`, the practices around `Fall` ratings can differ significantly between grid operators:
+
+* Assumed start and end dates can be different.
+* The FERC order specifies only that they must be updated _at least_ annually.  In practice, the times they may be changed can be different.
+
+The diagram below illustrates an example of rating providers with different season definitions.  Consider the challenges 
+for `Transmission Provider 1` to exchange seasonal ratings with `Ratings Provider A` and `Transmission Provider 2`:
+![Complex, Interweaving Seasonal Schedules](../images/ComplexSeasonalSchedules.svg)
+
+This decision record describes seasonal rating support in TROLIE.  
+
+## Decision
+
+TROLIE will add support for a seasonal clearinghouse, using the same pattern as used by forecasted and 
+real-time ratings.  Support for either accepting proposals or querying snapshots is technically optional, 
+although it is likely most Transmission Providers must support at least sharing 
+their snapshots of in-use seasonal ratings.  In practice, clearinghouse implementations may take seasonal proposals, 
+seasonal ratings from modeling systems, seasonal ratings from other systems, or any combination of these into account.  
+
+The familiar TROLIE concepts of proposals, 
+snapshots and a clearinghouse have multiple benefits for seasonal ratings:
+
+* While there are no EMS operator overrides or topology conditions to consider like there would be with AARs, there are still jointly-owned facilities and tie lines where multiple ratings may be submitted by different Ratings Providers.  
+* Some Transmission Providers may elect to manually validate proposed seasonal ratings before using them, as is common in existing practices.  The distinction between proposal and in-use snapshot provides a discrete step in the overall data flow where such manual validation may be inserted if desired.  
+
+
+### Defining Seasonal Ratings by Date Instead of Season Names
+
+Seasonal ratings in TROLIE will always be defined via start and end dates, rather than named seasons such 
+as `Fall` or `Summer`.  This way, the definition of what a rating provider is 
+submitting or a transmission provider is presenting
+can be more transparent and precise, and is not explicitly coupled to any one entity's 
+choices as to their season definitions.  
+
+The pre-defined "named" seasons that are included in proposal and snapshot definitions are included in headers, 
+but only provided as interop debugging hints.  
+
+### Alignment of Seasons and Flexibility of TROLIE Server Implementations
+Defining seasonal ratings in terms of start and end dates creates great flexibility in the shape of seasonal ratings that may be exchanged.  
+
+However, the specification explicitly **does not** imply that TROLIE servers **must** accept 
+seasonal ratings of any arbitrary start and end date at any time.  Transmission Providers 
+implementing TROLIE are ultimately free to decide how flexible they want to be.  
+
+For example, a Transmission Provider may choose only to accept seasonal ratings that 
+match that Transmission Provider's pre-defined season start and end dates.  Proposals 
+ for these seasons may then need to submitted before some cut-off time determined by 
+ the implementer.  Such proposals may be rejected using an HTTP 422 response, in
+ much the same fashion to forecasts.  
+
+TROLIE server implementations may reject proposals that do not adhere to the Transmission 
+Provider's business rules and practices.  
+
+
+## Consequences
+
+Seasonal rating support is implemented in the TROLIE [specification](../spec#tag/Seasonal).

docs/example-narratives/examples/seasonal-ratings-proposals-conditional.json

@@ -0,0 +1,175 @@
+{
+  "proposal-header": {
+    "source": {
+      "last-updated": "2025-10-31T15:05:43.044267100-07:00",
+      "provider": "UTILITY-A",
+      "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
+    },
+    "default-emergency-durations": [
+      {
+        "name": "emergency",
+        "duration-minutes": 240
+      }
+    ],
+    "power-system-resources": [
+      {
+        "resource-id": "8badf00d-145-in-service",
+        "alternate-identifiers": [
+          {
+            "name": "EMS.Name.145-in-service",
+            "authority": "TO-NERC-ID"
+          }
+        ]
+      },
+      {
+        "resource-id": "8badf00d-145-out-of-service",
+        "alternate-identifiers": [
+          {
+            "name": "EMS.Name.145-out-of-service",
+            "authority": "TO-NERC-ID"
+          }
+        ]
+      }      
+    ]
+  },
+  "ratings": [
+    {
+      "resource-id": "8badf00d-145-in-service",
+      "periods": [
+        {
+          "season-name": "WINTER",
+          "period-start": "2024-11-15T00:00:00-05:00",
+          "period-end": "2025-03-01T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "emergency",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "SPRING",
+          "period-start": "2025-03-01T00:00:00-05:00",
+          "period-end": "2025-06-15T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "SUMMER",
+          "period-start": "2025-06-15T00:00:00-05:00",
+          "period-end": "2025-09-01T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "FALL",
+          "period-start": "2025-09-01T00:00:00-05:00",
+          "period-end": "2025-11-15T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "resource-id": "8badf00d-145-out-of-service",
+      "periods": [
+        {
+          "season-name": "WINTER",
+          "period-start": "2024-11-15T00:00:00-05:00",
+          "period-end": "2025-03-01T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "emergency",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "SPRING",
+          "period-start": "2025-03-01T00:00:00-05:00",
+          "period-end": "2025-06-15T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "SUMMER",
+          "period-start": "2025-06-15T00:00:00-05:00",
+          "period-end": "2025-09-01T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        },
+        {
+          "season-name": "FALL",
+          "period-start": "2025-09-01T00:00:00-05:00",
+          "period-end": "2025-11-15T00:00:00-05:00",
+          "continuous-operating-limit": {
+            "mva": 160
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            }
+          ]
+        }
+      ]
+    }    
+  ]
+}