Add dashboard layout plan and scenario validation rules documentation

specifications/scenario_validation.md

@@ -0,0 +1,44 @@
+# Scenario Validation Rules
+
+Last updated: 2025-11-09
+
+This document captures the validation rules that must run before comparing two or more scenarios within the CalMiner application. The rules are enforced inside the scenario service layer and surfaced through the API and HTML workflows.
+
+## Comparison Preconditions
+
+All scenarios included in a comparison request **must** satisfy the following preconditions:
+
+| Rule                       | Description                                                                                                                                                              | Error Code                   | Client Message                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------- |
+| Same project               | Every scenario must belong to the same project identifier.                                                                                                               | `SCENARIO_PROJECT_MISMATCH`  | "Selected scenarios do not belong to the same project."                |
+| Active status              | Only scenarios in `draft` or `active` status may be compared. Archived scenarios are rejected.                                                                           | `SCENARIO_STATUS_INVALID`    | "Archived scenarios cannot be compared."                               |
+| Shared currency            | Scenarios must share the same `currency` value when provided.                                                                                                            | `SCENARIO_CURRENCY_MISMATCH` | "Scenarios use different currencies and cannot be compared."           |
+| Timeline coherence         | When both scenarios provide date ranges, they must overlap or touch (inclusive). Non-overlapping ranges raise a conflict.                                                | `SCENARIO_TIMELINE_DISJOINT` | "Scenario timelines do not overlap; adjust the comparison window."     |
+| Primary resource alignment | Scenarios must declare the same `primary_resource` (if set). When one is unset, the non-null value is applied to both. If both are set but differ, the comparison fails. | `SCENARIO_RESOURCE_MISMATCH` | "Scenarios target different primary resources and cannot be compared." |
+
+## Error Response Contract
+
+When a validation rule fails, the service layer raises a `ScenarioValidationError` (to be implemented) containing:
+
+- a machine-readable `code` from the table above,
+- a human-readable `message` designed for UI display,
+- a list of related `scenario_ids` that triggered the rule (if available).
+
+The API adapts the error into an HTTP `422 Unprocessable Entity` payload:
+
+```jsonc
+{
+  "detail": {
+    "code": "SCENARIO_PROJECT_MISMATCH",
+    "message": "Selected scenarios do not belong to the same project.",
+    "scenario_ids": [12, 19]
+  }
+}
+```
+
+HTML form flows display the `message` as a banner and set the HTTP status to `400`.
+
+## Future Considerations
+
+- Expand rules to cover incompatible simulation parameter configurations once parameter taxonomy stabilises.
+- Provide localized error message variants when the internationalization framework is introduced.