// Package store loads the baked JSON artifacts described in CONTRACT.md ยง4. // The data is immutable after Load; all accessors are safe for concurrent use. package store import ( "encoding/json" "errors" "fmt" "os" "path/filepath" "sort" "strings" "pulsecast/api/internal/model" ) // Store is the in-memory baked dataset. type Store struct { meta model.Meta sensors []model.Sensor sensorBy map[string]model.Sensor series map[string][]model.Point forecasts map[string]map[string]map[string][]model.ForecastPoint context model.ContextData } // Load reads every artifact from dir. It returns a usable (possibly partial) // store together with a joined error so callers can start the API and let // /api/readyz report 503 instead of crash-looping. func Load(dir string) (*Store, error) { s := &Store{ sensorBy: make(map[string]model.Sensor), series: make(map[string][]model.Point), forecasts: make(map[string]map[string]map[string][]model.ForecastPoint), } var errs []error if err := readJSON(filepath.Join(dir, "sensors.json"), &s.sensors); err != nil { errs = append(errs, err) } sort.Slice(s.sensors, func(i, j int) bool { return s.sensors[i].ID < s.sensors[j].ID }) for _, sensor := range s.sensors { s.sensorBy[sensor.ID] = sensor } if err := readJSON(filepath.Join(dir, "metrics.json"), &s.meta); err != nil { errs = append(errs, err) } if err := readJSON(filepath.Join(dir, "context.json"), &s.context); err != nil { errs = append(errs, err) } if err := loadSeries(dir, s); err != nil { errs = append(errs, err) } if err := readJSON(filepath.Join(dir, "forecasts.json"), &s.forecasts); err != nil { errs = append(errs, err) } for sensorID, scenarios := range s.forecasts { for scenario, horizons := range scenarios { for horizon, points := range horizons { sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) }) horizons[horizon] = points } scenarios[scenario] = horizons } s.forecasts[sensorID] = scenarios } return s, errors.Join(errs...) } func loadSeries(dir string, s *Store) error { var errs []error // Contract allows a single series.json mapping sensor id -> points. var combined map[string][]model.Point err := readJSON(filepath.Join(dir, "series.json"), &combined) switch { case err == nil: for sensorID, points := range combined { sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) }) s.series[sensorID] = points } case !errors.Is(err, os.ErrNotExist): errs = append(errs, err) } // Contract also allows series/.json; these override the combined file. entries, err := os.ReadDir(filepath.Join(dir, "series")) if err != nil { if !errors.Is(err, os.ErrNotExist) { errs = append(errs, fmt.Errorf("series dir: %w", err)) } return errors.Join(errs...) } for _, entry := range entries { if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") { continue } var points []model.Point path := filepath.Join(dir, "series", entry.Name()) if err := readJSON(path, &points); err != nil { errs = append(errs, err) continue } sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) }) s.series[strings.TrimSuffix(entry.Name(), ".json")] = points } return errors.Join(errs...) } func readJSON(path string, dst any) error { raw, err := os.ReadFile(path) if err != nil { return fmt.Errorf("read %s: %w", path, err) } if err := json.Unmarshal(raw, dst); err != nil { return fmt.Errorf("decode %s: %w", path, err) } return nil } // Meta returns the model/data metadata. func (s *Store) Meta() model.Meta { return s.meta } // Sensors returns the sensors sorted by id. func (s *Store) Sensors() []model.Sensor { out := make([]model.Sensor, len(s.sensors)) copy(out, s.sensors) return out } // Sensor looks up one sensor. func (s *Store) Sensor(id string) (model.Sensor, bool) { sensor, ok := s.sensorBy[id] return sensor, ok } // Series returns the raw (15-minute) series for a sensor. func (s *Store) Series(id string) ([]model.Point, bool) { points, ok := s.series[id] return points, ok } // Forecast returns baked points for sensor/scenario/horizon. func (s *Store) Forecast(sensor, scenario, horizon string) ([]model.ForecastPoint, bool) { scenarios, ok := s.forecasts[sensor] if !ok { return nil, false } horizons, ok := scenarios[scenario] if !ok { return nil, false } points, ok := horizons[horizon] if !ok || len(points) == 0 { return nil, false } return points, true } // Context returns the baked weather/holiday context. func (s *Store) Context() model.ContextData { return s.context } // Versions returns data, model and context version strings. func (s *Store) Versions() (data, modelVersion, context string) { return s.meta.DataVersion, s.meta.ModelVersion, s.meta.ContextVersion } // Ready reports whether the minimum baked set is present. FastAPI health is // deliberately not part of readiness: the cache fallback is the safety net. func (s *Store) Ready() bool { if len(s.sensors) == 0 || s.meta.ModelVersion == "" || s.context.UpdatedAt.IsZero() { return false } for _, sensor := range s.sensors { if _, ok := s.Forecast(sensor.ID, "base", "7d"); ok { return true } } return false } // Len returns the number of loaded sensors (used in tests/logs). func (s *Store) Len() int { return len(s.sensors) }