Add source-weight diagnostics and PUF clone-dominance gate

[MaxGhenis]

Context

PolicyEngine/policyengine-us-data#1151 exposed a class of failure where support/clone rows can dominate final Enhanced CPS weights even when headline household totals look plausible. Microplex uses PUF and other donor sources differently, but the same production risk exists: a candidate can pass target-fit checks while final calibrated mass is concentrated in a support source or clone-like donor subset.

Microplex should keep source/provenance diagnostics out of the exported PolicyEngine H5, but we still need a separate artifact and release gate for this.

Proposed Microplex behavior

• During canonical mp build/scoring, write a sidecar source-weight diagnostics artifact outside the H5.
• Summarize final calibrated mass by construction source or source class, at least:
  • household count and weight share
  • person count and weight share
  • tax-unit count and weight share where available
  • positive-weight row counts
  • top source/source-class concentration
• Include PUF-specific diagnostics where supported by construction metadata:
  • original CPS/ASEC-like rows vs PUF donor/support rows
  • any explicit support-clone or donor-replay subset
  • top-tail/fixed-spine rows as a distinct fixed source, not mixed with ordinary PUF support
• Add an mp artifact gate that fails when source/support rows dominate beyond configured thresholds unless explicitly marked as an experimental build.
• Keep all source/provenance fields out of the exported PolicyEngine model variables; diagnostics live in sidecars and manifests only.

Acceptance criteria

• A canonical build writes a stable JSON sidecar, e.g. source_weight_diagnostics.json, referenced from manifest.json.
• mp300k_artifact_gates consumes the sidecar and reports a source_weight_diagnostics gate.
• The gate is required for replacement candidates and unmeasured/failing if the sidecar is missing.
• Tests cover a passing balanced-source payload and a failing clone/support-dominance payload.
• Export guards continue to reject source diagnostic variables in the H5.

Related us-data precedent: PolicyEngine/policyengine-us-data#1151

[MaxGhenis]

Progress update: PR #70 is merged for the artifact-gate side. Replacement gate reports now require a separate source_weight_diagnostics sidecar, package that sidecar through mp-300k gate inputs, and fail when support / PUF clone household-weight share exceeds the default 25% threshold. The issue remains open for the producer-side work: canonical builds still need to write source_weight_diagnostics.json from construction metadata before candidates can pass the new gate.

[MaxGhenis]

Producer-side follow-up is now open in #71. It writes source_weight_diagnostics.json for saved US Microplex artifact bundles, references it from manifest.json, and keeps the diagnostics out of the exported PolicyEngine H5. This pairs with #70 gate-input requirement; once merged, new saved artifacts should carry the sidecar needed by the source-weight diagnostics gate.

[MaxGhenis]

Follow-up #72 adds the remaining entity-level source shares requested here: household, person, and tax-unit counts plus weight shares where available, including a distinct Forbes fixed-spine breakout by reserved entity ID ranges. This keeps the diagnostics sidecar-only and out of the H5.

[MaxGhenis]

Implemented across #70, #71, and #72: source-weight diagnostics are required by the mp-300k artifact gates, canonical saved artifacts now write source_weight_diagnostics.json and reference it from manifest.json, the diagnostics stay out of the exported H5, and the sidecar reports household/person/tax-unit source shares with support and PUF-support dominance metrics.