Isolate shared policy from later reforms and repair clone routing

[MaxGhenis]

Why

The Astra review of country 2.0.1 reproduced four simulation-isolation defects on the shipping runtime, plus a county input-type inconsistency and two documentation errors. Ordinary simulations deliberately share the default policy state: share_spm_policy hands each one the shipped parameter tree, its warm at-instant caches and the shared instance's variable objects, because rebuilding a 130,000-parameter tree per household request is not affordable (a clone takes 1.5–2.0 s; a warm household build takes 0.03 s). What was shared was not protected.

1 (P1). A later parameter reform contaminated every other simulation. Core's Simulation.apply_reform calls reform.apply(system) directly instead of constructing the reform. That bypasses the defensive parameter clone in Reform.__init__ and edits whatever tree the system hands it. Reproduction: two ordinary single-person simulations on $50,000 both calculate $4,016 of income tax. After a.apply_reform({"gov.irs.deductions.standard.amount.SINGLE": {"2024": 100_000}}), a newly built, unreformed simulation calculates $3,718, and the module-level system's own SINGLE standard deduction has moved from 14,600 to 100,000. The same contamination leaks between tests in one process: running this PR's tests against the old code also breaks five unrelated pre-existing tests.

2 (P1). A reformed clone's calc() calculated the original. Core keeps self.calc = self.calculate and self.df = self.calculate_dataframe as bound methods in the instance dictionary (simulations/simulation.py:223-224), and its clone copies that dictionary verbatim (:1381-1416). So every alias on the clone still called the original. With income tax neutralized on the clone, clone.calculate("income_tax", 2024) returned [0.0] while clone.calc("income_tax", 2024) returned [4016.0]. clone.calc("spm_unit_spm_threshold", 2025) also filed its SPM receipt in the original simulation's provenance.

3 (P2). A variable a reform added could not take input. A population asks its entity for a variable before it builds a holder, and an entity resolves names through the system it is bound to. The shared system's entities still belonged to the shared instance, so set_input("clone_only_income", 2024, [123]) after AddedInputReform raised VariableNotFoundError for a variable the simulation's own registry held.

4 (P2). Traced parameter accesses were misattributed. Core writes the requesting simulation's tracer, trace and branch_name onto the root parameter node and caches the resulting TracingParameterNodeAtInstant there. On a shared tree, the second traced request reuses the first request's node. On core 3.30.2 it is worse than Astra found on 3.32.5: a traced simulation recorded zero parameter accesses. _calculate reads gov.abolitions and caches a non-tracing at-instant node before _run_formula ever marks the tree. The shared tree was also left holding a finished request's tracer for every later reader.

5 (low). The county FIPS text contract was not enforced. county_fips is documented as a five-digit string. Core maps a str variable onto the numpy object dtype, so the model stores an integer column as integers, and both readers of the column stringify before they ask the forecast provider. As a result, integer 36061 was silently accepted as New York County, while integer 6037 (Los Angeles County 06037 with its leading zero dropped) was reported as an absent county. Tightening is_county_fips alone would have changed nothing, because no model path hands it anything but text.

Documentation. The weight sanity check summed a weight variable through a weighted series, which multiplies each value by its own weight. With household weights of 2 and 3 it reported 13 households instead of 5, and trillions on the default population. The legacy enhanced-CPS bullet claimed that every resource output over the file fails closed. The test it cites checks county formatting, the count of unclassified units and the threshold, nothing else. Since the capped housing subsidy began requesting the SPM housing portion only for assisted units, and none of the 18 unclassified units is assisted, household net income and benefits do compute over the file (household_net_income sums to 6,944,802,734,080 across its 41,314 households).

What

Changes are in policyengine_us/spm.py unless noted otherwise.

• Copy-on-write parameter tree. Every simulation's system carries a read barrier: a per-base SharedParameter<Base> subclass whose parameters is a property. Whether anyone else reads a tree is recorded on the tree, and the mark is one-way. share_spm_policy, a branch copying its parent's system, and tracing's shallow root copy all mark it. Reform application arms the barrier. The first read of a marked tree inside that window clones it through core, which leaves the lender's tree and warm caches untouched. modify_parameters, load_extension and add_abolition_parameters, the three core methods that edit the live tree in place, detach outright. A variable-only reform never reads parameters, so the structural reform every simulation re-applies at its own start instant still pays nothing. Branches created with clone_system=False share their parent's policy deliberately, so they follow a parent's detach, matched on the children of their root. A branch's own reform detaches rather than rewriting its parent's tree.
• Clone alias routing. clone() rebinds every bound-method alias it copied to the clone, by method name, so an alias core adds later is repaired as well.
• Private entities. share_spm_policy shallow-copies the entities and binds them to the private system, keeping one object per key across entities, person_entity and group_entities. clone_spm_system now removes the second object per group-entity key that core's clone creates.
• Traced parameter receipts. A traced simulation on a shared tree gets its own shallow root: the same children, its own at-instant cache and trace fields, primed as traced. That costs microseconds instead of a 1.5 s tree clone. It also repairs the core ordering bug that recorded no accesses at all. On a tree nobody else reads, the root is marked traced in place, which keeps each parameter's parent pointing at the root whose cache an edit has to clear.
• County FIPS. The provider records, by (year, county), which counties the model received as something other than text, at the one point that still sees the type. It rejects them before its own memo when a county measurement needs them. Re-setting the input re-derives that year's record, so a corrected input goes through. Only a clone inherits the record, and it also covers a reform simulation's baseline arm. Nothing is scanned when the selection is not county-based. is_county_fips enforces the text contract for direct callers. Anyone who never asks for a county is still never asked for one: geography_kind="national" computes over the same population.
• Pinned systems. tools/pinned_tbs.py keys its cache on the parameter tree as well as the system, because a system now keeps its identity while detaching a tree. NY's decoupled EITC and CTC would otherwise have gone on reading pre-reform federal parameters.
• Pickling. The shared-policy class is published under its own name, so systems built on it still pickle.
• Docs. docs/usage/microsimulation.md is corrected, along with the docstring of test_legacy_enhanced_cps_lacks_source_backed_spm_independence_roles. That test now asserts its premise instead of stating it in prose: none of the 18 unclassified units receives housing assistance, out of 870 assisted units.

Adversarial review of this change

Before asking for review, I ran a four-lens adversarial review of the first pushed head (c7e2f9a179), covering copy-on-write, clones and entities, tracing and county, and performance and test quality. Every raised finding was then verified independently. 27 were raised and 18 confirmed, including real regressions in that first pass:

• Tracing gave each branch its own root, so a traced simulation stranded its shared-policy branches on the unreformed tree. The model's own formulas create such branches (itemizing vs not itemizing, the state EITC refundability branches, marginal tax rates), so a traced calculate → apply_reform → calculate returned pre-reform numbers. The verifier's constructed case was off by $2,860.
• Ownership was tracked on the borrowing system rather than the tree. A lender that had detached kept writing in place for its borrowers, and a branch's reform rewrote its parent's tree.
• A shallow traced root kept serving stale values after an in-place edit.
• A tuple of variable-only reforms paid for a full tree clone: 1.29 s, now 0.001 s.
• The county record never cleared, was not keyed by period, leaked into new simulations and skipped the baseline arm.

All 18 are fixed. Each has a test that fails against c7e2f9a179 and passes here, confirmed by running them against that head's spm.py. Two residuals are documented rather than fixed:

• A county rejection is scoped to a county code and year, not to a row, because the county has already been stringified before it reaches the provider.
• Core's holder.set_input bypasses the country's set_input, so that one channel behaves exactly as before.

Verification

Run locally on macOS with Python 3.14, policyengine-core 3.30.2 and spm-calculator 1.0.0, rebased on upstream/main at 2cc6f045ab.

Run	Result
uv run ruff format . && uv run ruff check .	clean
pytest policyengine_us/tests/ --ignore=…/policy/contrib --ignore=…/microsimulation (the test-other-python job; covers tests/core and tests/unit)	581 passed, 1 skipped, exit 0
pytest policyengine_us/tests/microsimulation (the test-microsimulation job)	82 passed, 4 skipped, exit 0
make test-yaml-reform	exit 0
make test-yaml-structural	exit 0
test_batched.py …/baseline/gov/states/ny (exercises the pinned NY systems)	567 passed, exit 0
test_batched.py …/baseline/household	exit 0
New and changed tests against upstream/main's spm.py	test_spm_system.py alone: 9 failed, 45 passed, where the failures are exactly the new county and entity tests and every pre-existing test passes; the isolation file: 19 of 25 failed

The microsimulation count is one lower than before the rebase because upstream's MA CCFA revert (#9458) collapsed a two-case parametrized test into one.

Performance is unchanged for ordinary simulations. A warm household Simulation(situation=…) build takes 0.02–0.05 s and a warm calculate about 0.2 s. Tests pin that an ordinary simulation, a variable-only reform and a tuple of them all keep sharing the tree. A parameter reform pays the detach once. Traced calculations are about 13% slower, because tracing now actually records parameter accesses, which it previously never did on this core.

Not addressed here

These Astra findings need model or release decisions rather than runtime isolation, and are left for PR B:

• Finding 1: SPM geography changes CARE eligibility for an assisted household.
• Finding 6: dataset rejection omits the public poverty aliases.
• Finding 7: the batch runner can report success after pytest exits non-zero.
• Finding 8: the country default enforces neither immutability nor model certification.
• Heavy-subdirectory splitting omits .yml files.

🤖 Generated with Claude Code

[MaxGhenis]

Superseded by #9467, which carried this work to main (see its provenance table).