Add execution receipt schema v1 for published results

changelog.d/570.added.md

@@ -0,0 +1 @@
+Add execution receipt schema v1 (`policyengine.provenance.receipt`), which records exactly what produced a UK result. It records the installed wrapper, model and core versions, with wheel hashes only when the builder verified them against the wheel RECORD, plus the data release and the SHA-256 of the simulated dataset bytes. The certificate digest is attached only when the certificate covers that model, core, dataset and wrapper. The receipt also carries reform and baseline digests, which refuse modifiers they cannot bind, and the fiscal-year convention. Digests use RFC 8785 canonical JSON over strict JSON values (`policyengine.provenance.canonical`), and the JSON Schema ships at `policyengine/data/schemas/execution_receipt.v1.schema.json`.

docs/_quarto.yml

@@ -54,6 +54,7 @@ website:
           - reference/index.md
           - countries.md
           - release-bundles.md
+          - receipts.md
           - data-publishing-design.md
           - examples.md
           - dev.md

pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-    "pydantic>=2.0.0",
+    "pydantic>=2.10.0",
     "pandas>=2.0.0",
     "h5py>=3.0.0",
     "microdf_python>=1.3.0,<1.4",
@@ -69,6 +69,7 @@ dev = [
     "mypy>=1.11.0",
     "pytest-cov>=5.0.0",
     "hypothesis>=6.100.0",
+    "rfc8785>=0.1.4",
     "policyengine-core==3.33.0",
     "policyengine-us==2.2.1",
     "policyengine-uk==2.125.1",
@@ -96,6 +97,9 @@ testpaths = [
 filterwarnings = [
     "ignore::pydantic.warnings.PydanticDeprecatedSince20",
 ]
+markers = [
+    "real_install: runs the receipt's loaded-package check against the real installation",
+]
 
 [tool.ruff]
 line-length = 88

scripts/generate_receipt_schemas.py

@@ -0,0 +1,60 @@
+"""Write the published JSON Schemas for policyengine.py receipt contracts.
+
+The Pydantic models in ``policyengine.provenance.receipt`` are the source;
+the schema files under ``src/policyengine/data/schemas/`` are what other
+languages consume. ``tests/test_execution_receipt.py`` checks that the two
+accept and reject the same receipts.
+
+Usage::
+
+    python scripts/generate_receipt_schemas.py          # write
+    python scripts/generate_receipt_schemas.py --check  # fail if stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_DIR = REPO_ROOT / "src" / "policyengine" / "data" / "schemas"
+os.environ.setdefault("POLICYENGINE_SKIP_COUNTRY_IMPORTS", "1")
+sys.path.insert(0, str(REPO_ROOT / "src"))
+
+from policyengine.provenance.receipt import ExecutionReceipt  # noqa: E402
+
+SCHEMAS = {
+    "execution_receipt.v1.schema.json": ExecutionReceipt.json_schema,
+}
+
+
+def render(builder) -> str:
+    return json.dumps(builder(), indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--check", action="store_true")
+    args = parser.parse_args(argv)
+    stale = []
+    for filename, builder in SCHEMAS.items():
+        path = SCHEMA_DIR / filename
+        content = render(builder)
+        if path.exists() and path.read_text() == content:
+            continue
+        if args.check:
+            stale.append(path)
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content)
+        print(f"wrote {path.relative_to(REPO_ROOT)}")
+    for path in stale:
+        print(f"{path.relative_to(REPO_ROOT)} is not up to date.", file=sys.stderr)
+    return 1 if stale else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/policyengine/__init__.py

@@ -48,3 +48,11 @@
     uk = None  # type: ignore[assignment]
 
 __all__ = ["Simulation", "outputs", "uk", "us"]
+
+# The wrapper's own version as imported, for receipts to compare with what is
+# installed when they are built.
+from policyengine.provenance.loaded import (  # noqa: E402
+    record_loaded_versions as _record_loaded_versions,
+)
+
+_record_loaded_versions(("policyengine",))