No target values in Populace
+Every calibration target value resolves from a Ledger fact. Populace can select, align, and weight targets; it cannot store observed values in country content.
+
+
+
+ production-backed contract map
+Ledger declares the truth. Populace executes the build.
++ The network below is generated from current Populace and Ledger source + contracts. The migration plan shows the remaining step: move + country-specific build choices into data specs that compile through + those contracts. +
+ +
+ 01 - system map
+
+ The ownership boundary.
+
+
+
+
+ Ledger
+
+
+ source of truth
+-
+
- source artifacts +
- normalized facts +
- target profiles +
- measurement contracts +
- source package manifests +
+ Populace
+
+
+ build interpreter
+-
+
- support spine compilation +
- source imputation +
- runtime evaluation +
- calibration +
- release gates +
+ Consumers
+
+ model use
+-
+
- policyengine.py +
- populace.dev +
- Thesis observations +
- calibration dashboard +
- future Axiom runtime +
+
+ rule 1
+
+
+ rule 2
+
+
+ rule 3
+
+
+ rule 4
+
+
+ Country packs are data
+Country-specific content is JSON or YAML: sources, support channels, imputation stages, target profiles, and release gates. No country loader Python.
+No aggregation knob
+All target estimates compile to summed model expressions. Counts are represented as entity-count expressions, not a separate target mode.
+Bindings are structured
+Targets identify Ledger records and model measurements through structured fields, not slash-separated target names.
+
+ 02 - concept network
+
+
+ The build concepts and how they depend on each other.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ generated from production source
+Spec concepts and attributes as executable dependencies.
+
+
+
+
+
+
+
+
+
+ fromtocontract
+
+
+ 03 - contracts
+
+
+ Current contracts plus the missing country-pack specs.
+
+
+ source registry
+
+
+ support spine
+
+
+ imputation graph
+
+
+ target profile
+
+
+ calibration profile
+
+
+ release contract
+
+
+
+ What data may enter the build
+Declares Ledger source packages, periods, artifacts, entity grain, and primary keys. Sources define what exists; support specs decide how to use them.
+Which records form the candidate universe
+Combines ASEC, FRS, PUF clones, ACS multispines, or prior-year samples into support channels with explicit initial mass allocation.
+How missing columns are filled
+Lists donor facts, recipient frames, predictors, constraints, sign/zero classifiers, weighted QRF settings, and lineage outputs.
+What evidence defines calibration
+Lives in Ledger. Each row points to source facts and gives measurement bindings for PolicyEngine today and Axiom when available.
+How targets become weights
+Declares target selection, weighting, loss, holdout rotation, solver settings, and protected gates. It never declares target values.
+What can publish
+Defines required source coverage, export variables, target coverage, critical target bands, smoke simulations, and policyengine.py compatibility.
+
+
+
+
+
+ Example: a target profile row
++ This proposed country-pack row shows the next target contract. The + display name can remain human-readable, but the row is identified + by Ledger selectors, structured dimensions, and model bindings. The + `value` comes only from the resolved Ledger fact. +
+{
+ "target_id": "irs_soi.child_tax_credit.amount.total",
+ "ledger_selector": {
+ "source_name": "irs_soi",
+ "source_measure_id": "child_tax_credit_amount",
+ "geography": { "level": "country", "id": "US" },
+ "period": { "policy": "latest_not_after_base_year" },
+ "dimensions": { "agi_range": "all", "child_count": "all" }
+ },
+ "measurement": {
+ "entity": "tax_unit",
+ "concept": "tax.credit.child_tax_credit.amount"
+ },
+ "bindings": {
+ "policyengine": {
+ "value_variable": "ctc",
+ "entity": "tax_unit",
+ "filter": { "variable": "tax_unit_count", "operator": ">", "value": 0 }
+ },
+ "axiom": {
+ "rule": "us.tax.credits.child_tax_credit.amount",
+ "status": "pending"
+ }
+ }
+}
+
+
+
+ Example: a support spine
++ This proposed country-pack contract declares the build universe. + Defaults handle common cases: include all records, split initial mass + equally across source channels, and preserve donor lineage. PUF clones + are support channels, not a separate population. +
+{
+ "support_spine": {
+ "base_year": 2024,
+ "channels": [
+ {
+ "id": "asec_2024",
+ "source": "ledger.us.census.cps_asec",
+ "period": 2024,
+ "initial_weight_share": "equal_source_mass"
+ },
+ {
+ "id": "asec_2023",
+ "source": "ledger.us.census.cps_asec",
+ "period": 2023,
+ "initial_weight_share": "equal_source_mass"
+ },
+ {
+ "id": "puf_clone",
+ "clone_from": ["asec_2024", "asec_2023"],
+ "donor_source": "ledger.us.irs.puf",
+ "initial_weight_share": "equal_source_mass"
+ }
+ ]
+ }
+}
+ 04 - compiler pipeline
+
+
+ From specs to a release bundle.
+
+
+
+
+ 1
+
+ Resolve Ledger snapshot
+Pin source packages, facts, target profiles, and source artifact hashes.
+
+ 2
+
+ Compile support universe
+Build linked people, households, tax units, benefit units, SPM units, and support-channel lineage.
+
+ 3
+
+ Assign geography
+Resolve atomic geography constrained by the lowest reliable source geography for each record.
+
+ 4
+
+ Run imputation graph
+Apply weighted QRF imputation with sign/zero classifiers, support guards, and donor lineage.
+
+ 5
+
+ Evaluate measurement bindings
+Use PolicyEngine today. Prefer Axiom bindings once they match the required variable surface.
+
+ 6
+
+ Calibrate weights
+Optimize a weighted capped percent-error loss, rotate holdouts, and preserve source support diagnostics.
+
+ 7
+
+ Gate and publish
+Export the H5, diagnostics, target registry, manifest, and compatibility metadata for policyengine.py.
+
+
+
+ loss proposal
+
+ Weighted mean capped percent error
++ The default calibration objective should be legible: per-target + capped absolute percent error, weighted by target scale and normalized + across broad measure classes. +
+target_error = min(abs(estimate - target) / denominator, cap)
+denominator = max(abs(target), floor_by_measure_class)
+target_weight = sqrt(max(abs(target), floor_by_measure_class))
+
+total_loss =
+ 0.5 * weighted_mean(amount_target_error)
+ + 0.5 * weighted_mean(count_target_error)
+ 05 - validation gates
+
+
+ Publish only if the contract holds.
+
+
+
+ gatewhat it catchesblocking rule
+
+
+ source coverageRequired Ledger source packages or facts are absent.All required source aliases resolve.
+
+
+ target coveragePopulace silently drops a target family that eCPS or eFRS covered.Required profile rows match or have reviewed exclusions.
+
+
+ export surfaceThe H5 misses variables required by the runtime or incumbent dataset.Required variables exist with finite values and expected entities.
+
+
+ critical targetsLarge misses on income tax, CTC, Social Security, SSI, or other release-critical aggregates.Generous but explicit error bands; failures block certification.
+
+
+ target lossSolver improves easy targets while degrading holdouts or national aggregates.Report train, holdout, full, amount, and count losses on common surfaces.
+
+
+ source supportCalibration leans on too little support for a target family or geography.Effective-sample and lineage diagnostics ship with every release.
+
+
+ runtime compatibilitypolicyengine.py cannot load, simulate, or summarize the release.Smoke simulations pass for the published bundle.
+
+
+ 06 - tax expenditure targets
+
+ Measure policy changes as reforms.
+
+
+
+ target fact
+
+
+ Ledger stores the observed tax expenditure or credit amount from the official source, with source period and dimensions.
+
+ measurement binding
+
+
+ The profile declares a simple reform, such as repealing a credit or deduction, and measures the fiscal delta.
+
+ calibration target
+
+ Populace calibrates to the simulated reform score, not a hand-coded proxy variable or a copied target value.
+{
+ "measurement": {
+ "entity": "tax_unit",
+ "policy_reform": {
+ "type": "parameter_override",
+ "parameter": "gov.irs.credits.cdcc.amount",
+ "value": 0
+ },
+ "measure": "baseline_tax - reform_tax"
+ }
+}
+ 07 - migration plan
+
+
+ Replace Python country content in stages.
+-
+
-
+ phase 0
+
Document current surfaces
+Freeze current Populace, eCPS, and eFRS export and target surfaces as comparison manifests.
+
+ -
+ phase 1
+
Move target contracts to Ledger
+Ledger owns profiles, selectors, measurement contracts, and source-period policies. Populace consumes profile-shaped objects.
+
+ -
+ phase 2
+
Define country build specs
+US and UK packs declare sources, support channels, geography assignment, imputation graph, target profile, and release gates in YAML or JSON.
+
+ -
+ phase 3
+
Compile specs to existing runtimes
+The interpreter emits the same support frames, imputations, target registries, and calibration inputs now produced by Python loaders.
+
+ -
+ phase 4
+
Remove country Python content
+Delete country loader Python once parity tests prove the specs compile to the same build artifacts or reviewed improvements.
+
+ -
+ phase 5
+
Switch measurement backend to Axiom
+Use PolicyEngine bindings until Axiom matches required variables. Then make Axiom the primary binding and keep PolicyEngine only for compatibility checks.
+
+
+ 08 - review surfaces
+
+ What should appear on populace.dev.
+
+
+
+
+
+
+
+
+
+
+ Build plan
+A visual expansion of the country spec: sources, support channels, imputation stages, target profile, and gates.
+Target registry
+Filterable target rows by source, geography, measure class, period, and binding. No slash-separated IDs as the primary UI.
+Target weights
+Show amount/count classes, target scale, solver weight, cap, denominator, and whether a zero-valued target has nonzero weight.
+Lineage graph
+Trace each export column and target estimate back to sources, imputation donors, runtime bindings, and calibration weights.
+Decisions to settle before implementation.
+
+
+
+ Should Ledger target profiles include default target weighting metadata, or should Populace own all solver weights?
+Should support channels default to equal source mass, equal record mass, or country-specific explicit weights?
+How strict should target-profile parity gates be while incumbent source packages move into Ledger?
+Which Axiom bindings are required before PolicyEngine bindings become compatibility-only?
+