Metadata-Version: 2.4
Name: aei-history-contract
Version: 0.2.0
Summary: Velorona local-history contract: HistoryRecord schema, retention/size pruning, deterministic 'what changed' rules and CSV export (Python reference + JS port).
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/AIDEdgeInc-Lab/aei-history-contract
Project-URL: Issues, https://github.com/AIDEdgeInc-Lab/aei-history-contract/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# aei-history-contract

The shared contract for Velorona's **local history** (data a customer keeps on their own machine; Velorona stores none of it):

- `schemas/` — `HistoryRecord` and `ChangeSummary` JSON Schemas (draft 2020-12).
- `src/aei_history_contract/core.py` — the Python **reference**: record validation, retention and size-cap pruning, the deterministic "what changed" rules, sentence rendering, CSV export.
- `js/aei_history_contract.js` — the JavaScript **port** (a classic script; `window.VeloronaHistoryContract` in a browser, `module.exports` in Node).
- `fixtures/golden.json` — inputs and expected outputs for every public function. Both ports must reproduce it exactly (`tests/`).

Rules in one place: values are compared only with the same entity, metric, `kind` and `source`; `then` is the stored row nearest to `now − n hours` within max(30 min, 25 % of n); "unchanged" means equal at the displayed precision; a missing value is `no_data`, never 0; text is built from fields only ("Rain rate at Site A: 1.2 mm/h now, 0.0 mm/h 5 h ago (model-derived, open-meteo, 14:00 UTC → 19:00 UTC)."), with no words like "worsening" and no forecasts of our own.

No I/O, no clock, no dependencies. Storage (IndexedDB in the Map, SQLite in the QGIS plugin) and capture hooks belong to each product.

Tests: `PYTHONPATH=src python -m pytest tests` (runs the JS port too; needs Node 18+). Regenerate fixtures only deliberately: `PYTHONPATH=src python fixtures/build_golden.py`, then review the diff.

Release discipline: any change to behaviour or schema = version bump in `pyproject.toml`, `core.py`, `js/aei_history_contract.js` (a test checks they agree), a CHANGELOG entry, and the owner's release approval before a product pins it.
