Clarify replication architecture in paper

Author: MaxGhenis

paper.md

@@ -30,13 +30,13 @@ bibliography: paper.bib
 
 # Summary
 
-The `policyengine` Python package [@policyengine_py] is an open-source analysis layer for tax-benefit microsimulation. It provides a common interface for running policy simulations, analyzing distributional impacts, and visualizing results across the US and the UK. It delegates country-specific tax-benefit calculations to dedicated country packages (policyengine-us and policyengine-uk) while providing shared abstractions for simulations, datasets, parametric reforms, and output analysis. Recent releases also treat the top-level `policyengine` version as a reproducibility boundary: it pins compatible country-model and microdata-package versions and resolves logical dataset names to immutable dataset artifacts. The package also powers an interactive web application at [policyengine.org](https://policyengine.org) that lets users explore policy reforms in both countries without writing code.
+The `policyengine` Python package [@policyengine_py] is an open-source analysis layer for tax-benefit microsimulation. It provides a common interface for running policy simulations and analyzing distributional impacts across the US and the UK. It delegates country-specific tax-benefit calculations to dedicated country packages (policyengine-us and policyengine-uk) while providing shared abstractions for simulations, datasets, parametric reforms, and output analysis. Recent releases also treat the top-level `policyengine` version as a reproducibility boundary: country data repositories publish immutable dataset artifacts with build-time provenance, and `policyengine` certifies runtime bundles that pin the country-model version, microdata-package version, and dataset artifact for an analysis. The package also powers an interactive web application at [policyengine.org](https://policyengine.org).
 
 # Statement of Need
 
 Tax-benefit microsimulation models are standard tools for evaluating the distributional impacts of fiscal policy. Governments, think tanks, and researchers use them to estimate how policy reforms affect household incomes, poverty rates, and government budgets. In practice, however, analysts often work across separate layers: statutory rules, representative microdata, reform definitions, and distributional outputs live in different tools and interfaces. Reproducing a baseline-versus-reform workflow, or carrying the same analysis pattern from one country model to another, therefore often requires bespoke scripts and project-specific conventions. Historical replication is especially difficult when policy rules, the analysis layer, and representative microdata are versioned independently and the analyst must reconstruct which combination produced a published estimate.
 
-The `policyengine` package provides an analyst layer that works across multiple country models under a consistent API. Users can supply their own microdata or use companion representative datasets. They can then compute the impact of current law or hypothetical reforms — including parametric changes to existing policy parameters and structural modifications to the tax-benefit system — on any household or a national population. The Simulation class supports individual household analysis, while population-level aggregate analysis uses representative survey datasets with calibrated weights. A single top-level release can identify the compatible country-model version, microdata-package version, and immutable dataset revision used in an analysis, reducing project-specific bookkeeping for replication. The source code and development history are public on GitHub.
+The `policyengine` package provides an analyst layer that works across multiple country models under a consistent API. Users can supply their own microdata or use companion representative datasets, then compute the impact of current law or hypothetical reforms — including parametric changes to existing policy parameters and structural modifications to the tax-benefit system — on any household or a national population. The Simulation class supports individual household analysis, while population-level aggregate analysis uses representative survey datasets with calibrated weights. A single top-level release can identify the runtime country-model version, microdata-package version, and immutable dataset artifact used in an analysis, while the data release records the build-time model provenance for that artifact. This reduces project-specific bookkeeping for replication.
 
 # State of the Field
 
@@ -62,13 +62,13 @@ The `policyengine` layer leaves reusable engine logic in PolicyEngine Core, coun
 
 The PolicyEngine software stack has four layers. PolicyEngine Core provides reusable simulation abstractions, versioned parameters, and dataset interfaces that country packages share [@policyengine_core]. The policyengine-us and policyengine-uk packages contain statutory logic, variables, and entity structures specific to each tax-benefit system. The `policyengine` package sits above them as the analysis layer: it defines shared simulation orchestration, structured output types, and canonical baseline-versus-reform workflows such as `economic_impact_analysis()`. Companion data repositories hold enhanced survey microdata derived from the Current Population Survey (CPS) [@woodruff2024enhanced_cps] and Family Resources Survey [@frs2020]. Figure 1 illustrates the runtime workflow: inputs flow into the Simulation layer, which produces the structured outputs.
 
-For reproducibility, the top-level package now acts as an orchestration boundary across these layers. Each bundled country manifest pins a compatible country-model package version and microdata-package version. The microdata packages publish release manifests that map logical dataset names to immutable Hugging Face artifacts and checksums. This lets analysts request a dataset such as `enhanced_frs_2023_24` while the runtime resolves it to a specific versioned artifact, and lets downstream systems record the exact analysis bundle used for a simulation.
+For reproducibility, the top-level package now acts as a certification boundary across these layers. Country data repositories build immutable microdata artifacts and publish release manifests with checksums and the exact country-model version used during data construction. Bundled country manifests in `policyengine` then certify the runtime bundle: the runtime country-model version, the microdata-package release, and the exact dataset artifact. Analysts can request a dataset such as `enhanced_frs_2023_24`, while the runtime resolves it to a specific versioned artifact and records both runtime and build-time provenance.
 
 ![PolicyEngine architecture. A microsimulation combines three input concepts — tax-benefit rules and parameters (policies), survey microdata (households), and behavioral responses (dynamics, defined in the country packages) — in the Simulation layer, which produces distributional impacts, fiscal impacts, regional breakdowns, poverty rates, and inequality metrics.](architecture.png){width="100%"}
 
-The `policyengine` package centralizes distributional methods; legislative implementation remains in the country packages. The cost is coordination overhead and the need to maintain a stable interface boundary across repositories.
+The `policyengine` package centralizes distributional methods; legislative implementation remains in the country packages.
 
-At runtime, a simulation combines a country model version, household microdata, and optional reform or behavioral-response inputs. The `Dynamic` class represents behavioral responses such as labor supply elasticities; the country packages define the relevant parameters, and the simulation pipeline applies them after the static policy reform. The analysis layer then produces reusable outputs for decile changes, program statistics, poverty, inequality, and regional impacts. Because the runtime exposes the resolved package-and-dataset bundle, the same result can be traced back to a specific `policyengine` release, country-model release, microdata release, and versioned dataset artifact.
+At runtime, a simulation combines a country model version, household microdata, and optional reform or behavioral-response inputs. The `Dynamic` class represents behavioral responses such as labor supply elasticities; the country packages define the relevant parameters, and the simulation pipeline applies them after the static policy reform. The analysis layer then produces reusable outputs for decile changes, program statistics, poverty, inequality, and regional impacts. Because the runtime exposes the resolved certified bundle, the same result can be traced back to a specific `policyengine` release, runtime country-model release, microdata release, versioned dataset artifact, and build-time country-model version.
 
 The following example computes a household's net income under baseline law and under a reform that doubles the US standard deduction for single filers: