Correct the amterr lab's solver description against the R code

paper/snapshot/labs/amterr/ANALYSIS.md

@@ -5,7 +5,10 @@ top of the 856/856 benefit-parity result (axiom-oracles#268) and the
 Giannella/Molin raw-variable reconstruction (github.com/giannella/snap_qc,
 run for FY2024 in this lab: `reconstruct_co_fy2024.R`). Revised 2026-10-03:
 layer 3, the software-cause split and the cost-share comparison were
-recomputed and corrected, and the weight vintage is now stated (see
+recomputed and corrected, and the weight vintage is now stated. Revised
+2026-10-04: the solver description was corrected against the R code, and
+layer 3 now says what the solver's moves did in each non-reproduced case
+and flags the weakly identified matches (see
 [revision history](#revision-history)). Every figure below that is computed
 from the QC file is regenerated by `audit_claims.py` into
 `claims_audit.json`; `README.md` gives the pins and commands to rerun the
@@ -92,26 +95,55 @@ caught in our own encoding.
 The Giannella/Molin solver (FY2024 adaptation, smoothing off) starts from
 the file's edited inputs (household size, earned and unearned income, rent,
 utilities and deductions) and moves only the input named by the case's first
-finding (ELEMENT1): earned or unearned income, rent, the utility allowance,
-medical, dependent care or child-support deduction in $3 steps, or household
-size by one person for element 150 (natures 7, 12, 14, 16). Income steps
-stop once the recomputed benefit passes RAWBEN (the benefit the agency
-issued). Rent, utility and deduction steps also stop within $3 of it. Steps
-that lower an input stop at zero; rent and utility steps also stop when the
-shelter deduction reaches its cap; every step stops when the benefit reaches
-$0 or after 1,000 steps. Rows the solver labels
-`util_up` or `util_down` then have the utility allowance set to the nearest
-value above (or below) the file's UTIL that more than 5 filtered cases in
-that state and calendar year use; a `util_down` row with no such value is
-set to 0. When ELEMENT1 is outside those lists the inputs stay as they are
-(`correctednotes == "no_change"`). The Axiom
-engine, which reproduces all 856 Colorado FSBEN values at zero tolerance on
-the file's inputs (axiom-oracles#268), then computes the benefit on the
-solver's inputs, and the result is compared with RAWBEN at the file's own $5
-editing tolerance. Below, "moved" means at least one of the eight replayed
-inputs differs from the file value it started from. (The solver's
-`correctedamount` column misses two utility rows, 202403-40765 and
-202404-40803, because it is recorded before the utility snap.)
+finding (ELEMENT1).
+
+- **Household size** moves once, by one person, for element 150: one fewer
+  for natures 12, 14 or 16 and one more for nature 7. The nature code alone
+  sets the direction, so the move can take the benefit away from RAWBEN (the
+  benefit the agency issued). It does in 2 of the 7 Colorado household-size
+  moves, 202310-40265 and 202402-40618.
+- **Earned or unearned income, rent, the utility allowance, and the medical,
+  dependent care or child-support deduction** move in $3 steps toward
+  RAWBEN. Income steps stop once the recomputed benefit passes RAWBEN; rent,
+  utility and deduction steps also stop within $3 of it. Steps that lower an
+  input stop at zero; rent and utility steps also stop when the shelter
+  deduction reaches its cap (when raising) or zero (when lowering);
+  income-raising steps stop when the uncapped benefit falls below zero; and
+  all steps stop when the benefit reaches $0 or after 1,000 steps. Where
+  RAWBEN is at or above the maximum allotment, which the benefit cannot
+  pass, income-lowering steps continue until the income reaches zero or the
+  step limit. Where it is at or below a one- or two-person unit's minimum
+  benefit, which the benefit cannot fall below, income-raising steps
+  continue until the uncapped benefit falls below zero or the step limit.
+- **The utility reset** then applies to every row the solver labels
+  `util_up` (RAWBEN above FSBEN) or `util_down` (RAWBEN below FSBEN). The
+  candidates are the utility amounts that more than 5 cases report in the
+  same state and calendar year, counting cases of any review status that
+  pass the solver's consistency filters (listed under Results). A `util_up`
+  row takes the candidate above the file's UTIL that lies nearest the
+  amount its steps reached, and keeps that stepped amount if no candidate
+  lies above. A `util_down` row takes the candidate below the file's UTIL
+  nearest its stepped amount, and is set to 0 if none lies below. The reset
+  can also take the benefit away from RAWBEN: in 202405-40908 it leaves the
+  benefit farther from RAWBEN than FSBEN. With the 2 household-size moves
+  above, these are the only 3 moved cases that end farther from RAWBEN than
+  FSBEN.
+- **Any other first finding** leaves the inputs as they are
+  (`correctednotes == "no_change"`).
+
+The Axiom engine, which reproduces all 856 Colorado FSBEN values at zero
+tolerance on the file's inputs (axiom-oracles#268), then computes the
+benefit on the solver's inputs, and the result is compared with RAWBEN at
+the file's own $5 editing tolerance. Below, "moved" means at least one of
+the eight replayed inputs differs from the file value it started from. The
+solver's `correctedamount` column is not the final change: household-size
+moves never write it, so it is 0 in all 7, and it is recorded before the
+utility reset, so it differs from the final change in all 15 utility rows
+and is 0 in 2 of them, 202403-40765 and 202404-40803, which only the reset
+moved. `audit_claims.py` checks two parts of this account against the
+solver's output: its port of the solver's benefit formula reproduces all 283
+recreated benefits, and the reset rule above, applied to each row's stepped
+amount, reproduces all 15 final utility amounts.
 
 FSBEN is a constructed variable: the final benefit Mathematica's model
 calculates from the edited inputs (technical documentation: listed as
@@ -127,10 +159,45 @@ certified to receive in the sample month (PDF p. 92).
 - 246 of 283 (86.9% of cases, 72.0% of the $99.1M replayed error dollars)
   reproduce the issued benefit within $5. In 230 the solver moved an input;
   in 16 nothing moved and |RAWBEN − FSBEN| ≤ $5 already.
-- 37 do not reproduce. In 20 the solver moved an input and stopped short.
-  In 17 nothing moved: 14 `no_change` rows and 3 rows where the solver's
-  element applied but it stopped before moving. For those 17 the replayed
-  input is the file's input, so the engine returns FSBEN.
+- 60 of the 230 are weakly identified. In each, the issued benefit lies
+  within $5 of a stretch where the solver's benefit formula is flat in the
+  moved input: the maximum allotment, the minimum benefit, or the benefit
+  past the shelter-deduction cap. By the solver's formula, every amount of
+  the input on that stretch reproduces the issued benefit, so the match
+  bounds the input on one side at most. 2 of the 60, 202403-40765 and
+  202404-40803, reproduce at every utility amount and bound it on neither
+  side. 31 of the 60 are above the $56 threshold.
+  - 53 are at or within $5 of the maximum allotment, which caps the
+    benefit. In 34 of them RAWBEN is the maximum and the solver lowered an
+    income. The solver pays the maximum whenever net income is zero or
+    less, and net income never falls as income rises, so every value of
+    that income up to the point where net income reaches zero yields the
+    maximum. The steps, which cannot pass RAWBEN, ran that income down to
+    $0 in 32 and to the 1,000-step limit in 2. In the other 19 the solver
+    moved rent (15), the utility allowance (3) or the medical deduction (1),
+    and every further amount in the same direction keeps the benefit within
+    $5 of RAWBEN.
+  - 4 are at the $23 minimum benefit of a one- or two-person unit.
+  - 3 are rent increases that stop within $14 of the shelter-deduction cap.
+    Past the cap, rent no longer changes the benefit, which stays within $5
+    of RAWBEN.
+
+  Not counted: 7 matches whose lowered input reaches no flat stretch,
+  because the steps took it to $0 (4) or its band of matching amounts runs
+  down to $0 (3).
+
+  The solver exports an `at_max` flag to mark capped cases (the uncapped
+  benefit on the replayed inputs is at least the maximum allotment less
+  $5). It is set for 54 of the 246 matches: 52 of the 53, one household-size
+  match and one match where nothing moved.
+- 37 do not reproduce. In 20 the solver moved an input: in 9 its $3 steps
+  stopped short of RAWBEN; in 6 they reached within $3 of it and the
+  utility reset then moved the input off that match (202310-40297,
+  202312-40456, 202312-40513, 202402-40603, 202405-40908 and 202409-41321);
+  and in 5 the one-person household-size move missed. In 17 nothing moved:
+  14 `no_change` rows and 3 rows where the solver's element applied but it
+  stopped before moving. For those 17 the replayed input is the file's
+  input, so the engine returns FSBEN.
 - The solver's own recomputed benefit and the engine agree on the within-$5
   classification for all 283 cases (246 reproduced, 37 not).
 
@@ -140,11 +207,14 @@ with an input error on that element; it does not identify which input the
 agency had wrong, and it does not rule out a computation error that a moved
 input absorbed. A non-reproduced case does not by itself show a computation
 error: the solver tries one element in one direction, so multi-element and
-household-composition errors also land among the 37.
+household-composition errors also land among the 37, as do the 6 cases the
+utility reset moved off a match their steps had reached.
 
 The replay outcome does not separate the layer-2 computational findings. Of
 the 26 cases that carry one, 13 reproduce ($3.6M/yr, 3.2% of Colorado error
-dollars), 10 do not ($3.5M, 3.1%) and 3 were not replayed. Among the 13 are
+dollars), 10 do not ($3.5M, 3.1%) and 3 were not replayed. 2 of the 10,
+202310-40297 and 202312-40456, are among the 6 cases the utility reset moved
+off a match. Among the 13 are
 202404-40794 and 202404-40823, which reproduce after the solver moved the
 child-support deduction and whose finding is 366/56/17 (computer programming
 error).
@@ -177,7 +247,9 @@ What the replay shows for these cases:
   for those cases. It does not show what facts the agency recorded or what
   the agency's system computed from them.
 - In the other 3 the solver moved a different finding's input, and the
-  engine's benefit matches neither RAWBEN nor FSBEN.
+  engine's benefit matches neither RAWBEN nor FSBEN. In 2 of them,
+  202312-40456 and 202312-40513, the utility steps had reached within $3 of
+  RAWBEN before the reset moved the input off that match.
 - 7 of the 10 broad-coded findings concern the benefit computation (520 in
   six cases; 362/52 in one). These 7 computation candidates carry $2.0M/yr,
   1.8% of Colorado error dollars. The other 3 are income or eligibility
@@ -225,8 +297,10 @@ for codes 20/21 and $1,210M (14.9%) for codes 10/22; neither reproduces.
   2 ($0.8M) it moved rent.
 - 2 do not reproduce ($2.4M/yr): 202312-40513 and 202401-40548. In both the
   software-coded finding (331/44/17 and 350/44/17) is on an element the
-  solver never moved; it moved ELEMENT1 (364 and 363). The replay does not
-  show that the computation logic failed in either case.
+  solver never moved; it moved ELEMENT1 (364 and 363). In 202312-40513 its
+  utility steps had reached within $3 of RAWBEN before the reset moved the
+  input off that match. The replay does not show that the computation logic
+  failed in either case.
 - Mass-change (19) findings in these 16 are on RSDI (4 cases), SSI (2) and
   the medical deduction (1); programming (17) findings are on RSDI, SSI,
   child support received and the child-support deduction. None is on rent
@@ -281,8 +355,9 @@ above the threshold. The 7 candidates are 7 sampled cases.
 - The engine replay checks the benefit computation. Eligibility-side errors
   (person included or excluded) enter only through the solver's household
   size step.
-- The solver moves one element in $3 steps; $5 is the comparison tolerance.
-  Exact-tolerance rates are not meaningful at this layer.
+- The solver moves one element: in $3 steps, then a reset for the utility
+  allowance, or by one person for household size. $5 is the comparison
+  tolerance. Exact-tolerance rates are not meaningful at this layer.
 - FY2024 was evaluated through the compile-time COLA overlay at the nominal
   period, as in the parity run; rulespec-us#759 (the dependency inversion
   that would remove the overlay) was still open on 2026-10-03.
@@ -367,3 +442,29 @@ P.L. 119-21 sec. 10105. Rerun instructions and pins: `README.md`.
     that FY2025 was still being measured.
   - Paths in the scripts are configurable; `README.md` gives pins and
     commands. `phase_a_classification.json` lives one directory up.
+- **2026-10-04.** The solver description now matches
+  `reconstruct_co_fy2024.R`. `audit_claims.py` ports the solver's benefit
+  formula and re-applies the utility reset, and the new counts below come
+  from it. Changes:
+  - Utility reset: the solver takes the candidate nearest the amount its
+    steps reached. The 2026-10-03 text said the candidate above (or below)
+    the file's UTIL nearest that UTIL; that rule gives the final amount in
+    8 of the 15 utility rows. The candidates are counted over filtered cases of any review
+    status, and a `util_up` row with no candidate above keeps its stepped
+    amount.
+  - Stop rules: rent and utility steps also stop at a zero shelter
+    deduction when lowering, and income-raising steps stop when the
+    uncapped benefit falls below zero. Where RAWBEN is at or above the
+    maximum allotment, income-lowering steps run on to zero income or the
+    step limit, and at or below the minimum benefit, income-raising steps
+    run on until the uncapped benefit falls below zero.
+  - Household size: the nature code sets the direction. The move takes the
+    benefit away from RAWBEN in 2 of the 7 Colorado cases.
+  - "In 20 the solver moved an input and stopped short" was true of 9 of
+    the 20. In 6 the steps reached within $3 of RAWBEN and the utility reset
+    moved the input off that match; in 5 the household-size move missed.
+  - The `correctedamount` note now covers household-size moves and all 15
+    utility rows.
+  - Added: 60 of the 230 moved matches are weakly identified, 34 of them
+    because RAWBEN is the maximum allotment and the solver lowered an
+    income.