Skip to content

Add versioned execution receipts#469

Draft
MaxGhenis wants to merge 1 commit into
mainfrom
codex/execution-contract-foundation
Draft

Add versioned execution receipts#469
MaxGhenis wants to merge 1 commit into
mainfrom
codex/execution-contract-foundation

Conversation

@MaxGhenis

Copy link
Copy Markdown
Contributor

Fixes #468

Why

PolicyEngine needs reproducible execution identity across its current Python runtime and the planned migration to Axiom and Populace. Mutable selectors such as latest, default, and dataset aliases describe intent, but they do not prove which runtime, rules, packages, or population artifact actually produced a result.

What changed

  • Add a strict, engine-neutral execution receipt schema v1.
  • Keep requested aliases separate from resolved runtime, numeric mode, package, ruleset, and population identities.
  • Distinguish actual package versions from the versions certified by a release manifest, without claiming unused release components were loaded.
  • Snapshot certified release context and compact TRACE bundle references using JSON-round-trippable Pydantic models.
  • Canonicalize request and result content with RFC 8785 JCS before hashing, giving Python, Rust, and TypeScript implementations a shared digest contract.
  • Validate receipt cross-references before run-record I/O, write execution-receipt.json, and bind it as the runtime artifact in the simulation TRACE record.
  • Export the contract from the public policyengine package and document it with a Towncrier fragment.

This gives API and application surfaces a stable provenance envelope during the Axiom/Populace transition while preserving the existing PolicyEngine TRACE representation.

Validation

  • uv run pytest — 736 passed
  • uv run mypy src/policyengine/execution.py — passed
  • make lint — Ruff formatting and lint checks passed
  • git diff --check — passed

Introduce an engine-neutral provenance contract and bind validated receipts into simulation TRACE run records.

Refs #468
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a versioned execution receipt contract

1 participant