sprint-0: fundaciones VMS-Sailor

Sprint 0 completo del producto VMS-Sailor (Vessel Management System
integrado para buques 30-40m). Brief de referencia en
VMS_Sailor_v2_Parte_*.md (intacto).

Core (vmssailor.core, 95.17% coverage, 99 tests verde):
- ShipCoord: sistema naval x_pp/y_cl/z_bl frozen
- Vessel, Deck, Bulkhead
- Equipment, EquipmentModel, Sensor, EquipmentSpec
- Tag, AlarmConfig, TagBinding, Scaling
- CardInstance, Bus, Topology con validacion 21 puntos I/O AR-NMEA-IO-v1.0
- Alarm, PermissiveRule, Condition
- Project agregado raiz con validacion cross-entity
- Persistencia portable .vmsproj (SQLite) con roundtrip verificable

Biblioteca curada seed (vmssailor.library):
- systems_catalog.json completo (catalogo maestro Parte 1 sec 7)
- 2 vessels: Sunseeker 76, Ferretti 850
- 2 motores: MTU 12V 2000 M96, Volvo D13-900
- 1 genset: Northern Lights M65C13
- yacht_motor_planeo.yaml (reglas heuristicas)
- TODO marcado data_source=seed_estimate - requiere validacion datasheets

Tools:
- vms-validate-library: CLI valida biblioteca completa
- vms-generate-test-project: CLI demo + verificacion roundtrip persistencia

Design System + 8 mockups HTML estaticos:
- docs/design_system.md (paleta Deep Ocean, gradientes, typography, motion)
- docs/brand/ (logo + variantes SVG)
- docs/mockups/splash, studio_main, runtime_overview,
  runtime_mimic_fuel (P&ID animado), runtime_alarms, runtime_trim (panel
  estrella con horizonte artificial), mobile_overview, mobile_trim
- docs/mockups/index.html (galeria)

Firmware (Sprint 12+ implementacion):
- firmware/ar_nmea_io_v1/src/config/pinout.h con macros GPIO

Decisiones autonomas documentadas en docs/decisions_sprint0.md.

Stack: Python 3.11 + uv + Pydantic v2 + SQLite stdlib + hatchling +
pytest 9 + ruff + mypy. Sin PySide6, FastAPI, Flutter ni firmware
funcional (entran en sprints siguientes).

Criterio de aceptacion Sprint 0: cumplido.
- uv sync: OK
- pytest: 99/99 verde
- cov vmssailor.core: 95.17% (objetivo >=80%)
- ruff: clean
- vms-validate-library: OK
- vms-generate-test-project: INTEGRIDAD OK

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vmssailor/core/alarm.py

@@ -0,0 +1,83 @@
+"""Instancia activa de alarma (estado runtime, no configuración).
+
+La **configuración** de una alarma vive en `AlarmConfig` (ver `tag.py`).
+La **instancia** de una alarma — qué se disparó, cuándo, quién acuso recibo —
+vive aquí.
+
+Estas instancias son las que persiste el Runtime en su tabla de alarmas y
+las que la API WebSocket transmite en mensajes `alarm_event`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from vmssailor.core.enums import AlarmPriority, AlarmState
+
+
+class Alarm(BaseModel):
+    """Una alarma activa o histórica en el Runtime."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(..., min_length=1, max_length=128, description="UUID o ID determinista.")
+    tag_id: str = Field(..., min_length=1, max_length=128, description="Tag que disparó la alarma.")
+    alarm_config_id: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        description="ID del AlarmConfig que se evaluó como verdadero.",
+    )
+    priority: AlarmPriority
+    state: AlarmState
+    timestamp_active: datetime = Field(
+        ..., description="Cuándo se disparó (entró en ACTIVE)."
+    )
+    timestamp_ack: datetime | None = Field(
+        default=None, description="Cuándo el operador hizo ack. None si nunca."
+    )
+    timestamp_cleared: datetime | None = Field(
+        default=None,
+        description="Cuándo la condición se resolvió. None si sigue presente.",
+    )
+    acknowledged_by: str | None = Field(
+        default=None,
+        max_length=128,
+        description="Usuario que hizo ack. None si nunca.",
+    )
+    message: str = Field(default="", max_length=512)
+    value_at_trigger: float | None = Field(
+        default=None,
+        description="Valor del tag al momento del disparo (snapshot para logbook).",
+    )
+
+    @model_validator(mode="after")
+    def _state_timestamps_consistency(self) -> Alarm:
+        if self.state == AlarmState.ACK and self.timestamp_ack is None:
+            raise ValueError(
+                "Alarma en estado ACK requiere timestamp_ack."
+            )
+        if self.state == AlarmState.CLEARED and self.timestamp_cleared is None:
+            raise ValueError(
+                "Alarma en estado CLEARED requiere timestamp_cleared."
+            )
+        if (
+            self.timestamp_ack is not None
+            and self.timestamp_ack < self.timestamp_active
+        ):
+            raise ValueError("timestamp_ack debe ser ≥ timestamp_active.")
+        if (
+            self.timestamp_cleared is not None
+            and self.timestamp_cleared < self.timestamp_active
+        ):
+            raise ValueError("timestamp_cleared debe ser ≥ timestamp_active.")
+        if (
+            self.acknowledged_by is not None
+            and self.timestamp_ack is None
+        ):
+            raise ValueError(
+                "acknowledged_by sin timestamp_ack es inconsistente."
+            )
+        return self