Source code for energy_data_retrieval.wind_catalogue.observations
"""Attach reviewed dated OEM observations without replacing configuration facts."""
from __future__ import annotations
import copy
import datetime
import hashlib
import json
from typing import Any
from energy_data_retrieval.pv_catalogue.catalogue import canonical_json
[docs]
def enrich_oem_history(
document: dict[str, Any], original: bytes, existing: list[dict[str, Any]], *, now: str
) -> list[dict[str, Any]]:
"""Apply an explicit record-ID/model crosswalk and checksum-pinned transcription.
Observations describe their historical boundary and original units. The caller
reviews every mapping; neither model-name similarity nor table position creates
an identity. Scalar specifications, aliases and creation times are preserved.
Replaying identical observations is idempotent; changing the same dated source
on an existing record raises instead of silently replacing the observation.
"""
if hashlib.sha256(original).hexdigest() != document["sha256"]:
raise ValueError("OEM original checksum mismatch")
datetime.date.fromisoformat(document["published_at"])
source = document["source_id"]
if not source or not document.get("revision"):
raise ValueError("Require source identity and revision boundary")
entries = document["entries"]
ids = [e["record_id"] for e in entries]
if (
not ids
or len(set(ids)) != len(ids)
or sorted(ids) != sorted(document["expected_record_ids"])
):
raise ValueError("Incomplete or duplicate reviewed mapping")
by_id = {x["record_id"]: x for x in existing}
if len(by_id) != len(existing):
raise ValueError("Duplicate catalogue identity")
result = []
for e in entries:
row = copy.deepcopy(by_id[e["record_id"]])
if (row["entity_type"], row["manufacturer"], row["model"]) != (
"equipment",
e["manufacturer"],
e["model"],
) or row.get("rated_power_kw") != e["identity_rated_power_kw"]:
raise ValueError("Reviewed configuration identity mismatch")
if not e.get("locator") or not e.get("boundary") or not e.get("facts"):
raise ValueError("Require locator, boundary and substantive facts")
observation = {
"source_id": source,
"published_at": document["published_at"],
"revision": document["revision"],
"locator": e["locator"],
"boundary": e["boundary"],
"facts": e["facts"],
"normalization": e.get(
"normalization", "Original units retained; no scalar substitution"
),
"confidence": "high",
"validation_status": "OEM statement; not independently validated performance",
}
ext = json.loads(row.get("extensions_json") or "{}")
history = ext.setdefault("oem_historical_observations", [])
prior = [o for o in history if o["source_id"] == source]
if prior:
if prior != [observation]:
raise ValueError("Immutable OEM observation changed")
result.append(row)
continue
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", []), source]))
ev["extensions_json"] = {
"prior_observation": ev.get("extensions_json"),
"source_id": source,
"locator": e["locator"],
"confidence": "high",
"normalization": "Dated nested historical observation; prior scalar facts preserved",
}
row.update(
extensions_json=canonical_json(ext),
field_sources_json=canonical_json(fs),
evidence_json=canonical_json(ev),
sources=sorted(set([*row["sources"], source])),
updated_at=now,
last_verified_at=now,
)
result.append(row)
return sorted(result, key=lambda x: x["record_id"])