Motivation (measured)
The imputation paper (github.com/PolicyEngine/imputation-paper) measured the cost of an unweighted donor fit on an informative design: the identical populace-fit estimator fit without SCF weights is 6× worse on net-worth Wasserstein-1 within the donor survey (135,871 → 829,158) and inflates the imputed net-worth q99 by 1.9–2.25× on the SCF→CPS population view — an error that energy distance, PRDC coverage, and a classifier two-sample test all tie on (only an uncapped tail metric catches it). On a weakly informative design (CPS person weights), weighting is free. A build cannot know in advance which regime a donor is in, so weighted fitting must be structural, not optional.
Current state
populace-fit already enforces this at the API: Frame fits default to typed design weights and weights="none" is the only unweighted path; the DataFrame front door (#290) makes weights explicit-required. Build code (e.g. us_runtime/puf_support.py) fits through this interface, so today's paths are safe.
Proposal
Make the guarantee auditable and future-proof at the build level:
- Audit artifact: every production fit records its resolved weight kind (design/importance/calibrated) in the build manifest; a release gate fails if any fit resolved unweighted (
"none") without an explicit allowlist entry stating why.
- Spec-level rule: if/when declarative step configs drive fits, a step without an explicit
weights: declaration is a build error (the DataFrame front door's no-default rule, lifted to the spec). This is the guard the old microplex spec engine lacked (the microplex-us#263 regression class).
🤖 Generated with Claude Code
Motivation (measured)
The imputation paper (github.com/PolicyEngine/imputation-paper) measured the cost of an unweighted donor fit on an informative design: the identical populace-fit estimator fit without SCF weights is 6× worse on net-worth Wasserstein-1 within the donor survey (135,871 → 829,158) and inflates the imputed net-worth q99 by 1.9–2.25× on the SCF→CPS population view — an error that energy distance, PRDC coverage, and a classifier two-sample test all tie on (only an uncapped tail metric catches it). On a weakly informative design (CPS person weights), weighting is free. A build cannot know in advance which regime a donor is in, so weighted fitting must be structural, not optional.
Current state
populace-fit already enforces this at the API: Frame fits default to typed design weights and
weights="none"is the only unweighted path; the DataFrame front door (#290) makes weights explicit-required. Build code (e.g.us_runtime/puf_support.py) fits through this interface, so today's paths are safe.Proposal
Make the guarantee auditable and future-proof at the build level:
"none") without an explicit allowlist entry stating why.weights:declaration is a build error (the DataFrame front door's no-default rule, lifted to the spec). This is the guard the old microplex spec engine lacked (the microplex-us#263 regression class).🤖 Generated with Claude Code