Source code for energy_data_retrieval.wind_catalogue.grid_connections

"""Replay reviewed grid-connection milestones without inferring commercial operation."""

from __future__ import annotations

import copy
import hashlib
import json
from datetime import date
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json


[docs] def enrich_grid_connections( document: dict[str, Any], original: bytes, existing: list[dict[str, Any]], *, now: str ) -> list[dict[str, Any]]: """Attach a complete, checksum-pinned project crosswalk as immutable observations. Grid synchronization is not COD, a completed reliability trial or a measured capacity. Preserve every scalar, including lifecycle and commissioned MW. Dates refer to the event, independently of the announcement publication date. """ if hashlib.sha256(original).hexdigest() != document["sha256"]: raise ValueError("Grid-connection original checksum mismatch") published = date.fromisoformat(document["published_at"]) if published > date.fromisoformat(now[:10]) or not document["source_id"]: raise ValueError("Require a published source identity") entries = document["entries"] ids = [entry["record_id"] for entry in entries] if not ids or len(set(ids)) != len(ids) or sorted(ids) != sorted(document["expected_ids"]): raise ValueError("Incomplete or duplicate grid-connection partition") by_id = {row["record_id"]: row for row in existing} if len(by_id) != len(existing): raise ValueError("Duplicate catalogue identity") result = [] for entry in entries: row = copy.deepcopy(by_id[entry["record_id"]]) if (row["entity_type"], row["name"], row["country_code"]) != ( "projects", entry["name"], entry["country_code"], ) or not entry.get("identity_basis"): raise ValueError("Explicit project crosswalk mismatch") if date.fromisoformat(entry["event_date"]) > published: raise ValueError("Event follows publication; forecasts are not achieved milestones") if entry["scope"] not in {"first_turbine", "all_turbines"}: raise ValueError("Require explicit grid-connection scope") count = entry.get("connected_turbines") if count is not None and (type(count) is not int or count <= 0): raise ValueError("Connected turbine count must be positive or unknown") if entry["scope"] == "first_turbine" and count not in {None, 1}: raise ValueError("First-turbine milestone cannot describe a full fleet") if not entry.get("locator") or not entry.get("remaining_milestones"): raise ValueError("Require locator and explicit completion limitations") observation = { key: entry[key] for key in ( "event_date", "scope", "connected_turbines", "locator", "identity_basis", "remaining_milestones", ) } observation.update( source_id=document["source_id"], published_at=document["published_at"], kind="reported", boundary="Grid connection only; not commercial operation", ) ext = json.loads(row.get("extensions_json") or "{}") history = ext.setdefault("grid_connection_observations", []) prior = [item for item in history if item["source_id"] == document["source_id"]] if prior: if prior != [observation]: raise ValueError("Immutable grid-connection observation changed") else: history.append(observation) fs = json.loads(row["field_sources_json"]) ev = json.loads(row["evidence_json"]) fs["extensions_json"] = sorted( set([*fs.get("extensions_json", []), document["source_id"]]) ) ev["extensions_json"] = dict( prior_observation=ev.get("extensions_json"), source_id=document["source_id"], locator=entry["locator"], publication_date=document["published_at"], confidence="high", normalization="Dated milestone only; scalar lifecycle and capacity preserved", ) row.update( extensions_json=canonical_json(ext), field_sources_json=canonical_json(fs), evidence_json=canonical_json(ev), sources=sorted(set(row["sources"] + [document["source_id"]])), updated_at=now, last_verified_at=now, ) result.append(row) return sorted(result, key=lambda row: row["record_id"])