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"])