PolicyEngine / PolicyEngine/policyengine-sim-api
Add the Stage 12 parallel v2 simulation path
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- Avg merge
- 10h 29m
- Merged PRs (30d)
- 7
Description
Objective
Add the Stage 12 v2 comparison path alongside the existing simulation services without replacing the current production calculation path or making v2 output authoritative.
Scope
- Deploy a separately named Modal v2 application.
- Run one report coordinator that starts baseline and reform as independent simulation functions before waiting for either result.
- Publish and consume a v2 version manifest that is separate from the existing v1 manifest.
- Resolve country-package and dataset versions exclusively from reviewed PolicyEngine.py
.pybundle files. - Provide a temporary authenticated direct Stage 12 runner for qualification.
- When
STAGE12_ENABLED=1, automatically start one Stage 12 comparison run after a supported production annual society-wide report is accepted. - Wait no more than five seconds for Modal to acknowledge the coordinator invocation, then return the unchanged production response without waiting for Stage 12 calculation or comparison.
- After Stage 12 aggregation, retrieve the production Modal result, compare the complete aggregate result objects exactly, and write a private
reports/comparison.jsonreceipt containing result digests and every differing scalar leaf. - Isolate Stage 12 dispatch, calculation, comparison, artifact, and persistence failures from the production result.
- Remove the shared runtime-control object, process-local dispatch queue, and periodic PostgreSQL cleanup function.
Deployment dependency
PolicyEngine/policyengine-api#3842 adds the comparison-result columns consumed by this runtime. That PR must merge and its v2 Alembic revision must run before this simulation PR merges. The production restricted PostgreSQL URL secret and environment configuration must also be present and pass the existing deployment validation.
The beta and prod GitHub environments both define STAGE12_ENABLED=0. Merging this PR therefore deploys the separate Modal application, separate v2 manifest, Cloud Run configuration, and temporary authenticated direct endpoint without automatically sending normal report submissions to Stage 12. Setting one environment value to 1 and deploying Cloud Run enables automatic runs in that environment; it does not change the existing production forwarding destination or result authority.
Acceptance criteria
- Existing v1 routing and user-visible result authority are unchanged.
- Baseline and reform simulations execute independently and are aggregated by the report coordinator.
- V1 and v2 manifests use distinct storage objects.
- Stage 12 resources deploy in both staging and production after prerequisites exist.
- Automatic runs remain disabled in both environments after the initial deployment.
- The five-second Modal-acknowledgement wait is the only Stage 12 work on the production request path.
- Direct Stage 12-only execution remains available independently of
STAGE12_ENABLEDwhen resources are configured. - No periodic Stage 12 function runs.
- Private artifacts expire through the existing 30-day storage lifecycle; temporary PostgreSQL rows remain until Stage 14.
- Local tests, formatting, focused type checks, container-import validation, and deployment-contract checks pass.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The issue names no repository implementation files, tests, or entry points; it does identify PolicyEngine.py .py bundle files and the private reports/comparison.json receipt. Start by reviewing the deployment dependency on PolicyEngine/policyengine-api#3842 and the existing deployment validation. Done means the listed v2 resources, isolated dispatch and comparison path, acceptance checks, and unchanged production authority are all verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- google-cloud, postgresql, python
- Domain
- backend, cloud, databases, devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100