From a11e29a0e0de8d3b7acbea905ab6055f677d77ae Mon Sep 17 00:00:00 2001 From: Jared Knowles Date: Mon, 3 Aug 2026 09:42:47 -0400 Subject: [PATCH] docs: use Wisconsin state govt (550000227544) as the cog_balances test government Standardises on the identifier other agents use for state governments, which is stable across corpus vintages and is the same id used against the live API. Verified in the bundled fixture, and it is strictly better coverage than the previous pick: Wisconsin reaches four of the five balance subtypes (adds workers_comp_trust via Y21) and carries BOTH wide->modern recipe bridges (X40->Z77 and X41->Z78), so a second recipe test is added. Y61 (other_insurance_trust) is absent for Wisconsin; no test depends on it. Also notes not to assert on gov_name -- the fixture carries both "WISCONSIN" and "WISCONSIN STATE GOVT" and the verb COALESCEs them. --- .superpowers/plans/2026-08-03-cog-balances.md | 67 +++++++++++++------ 1 file changed, 47 insertions(+), 20 deletions(-) diff --git a/.superpowers/plans/2026-08-03-cog-balances.md b/.superpowers/plans/2026-08-03-cog-balances.md index 472b12f..02088d0 100644 --- a/.superpowers/plans/2026-08-03-cog-balances.md +++ b/.superpowers/plans/2026-08-03-cog-balances.md @@ -23,16 +23,30 @@ ## The test government -`010000226085` — ALABAMA STATE GOVT. One government covers every case: +`550000227544` — **WISCONSIN STATE GOVT**. Use this govid and no other. It is +the identifier other agents have standardised on for state governments, it is +stable across corpus vintages, and it is the same id used against the live API +(`/api/v1/governments/550000227544/...`). Verified present in the bundled +fixture: | year | codes present | |---|---| -| 2011 | `X21`, **`X40`**, `Y07`, `Y08` | -| 2012 | `W01`, `W31`, `W61`, `X21`, `Y07`, `Y08`, `Z77` | +| 2011 | `X21`, **`X40`**, **`X41`**, `X42`, `X44`, `Y07`, `Y08` | +| 2012 | `W01`, `W31`, `W61`, `X21`, `X30`, `X47`, `Y07`, `Y08`, `Y21`, **`Z77`**, **`Z78`** | | 2019 | `W01`, `W31`, `W61`, `Y07`, `Y08` | -| 2020 | `W01`, `W31`, `W61`, `Y07`, `Y08` | +| 2020 | `W01`, `W31`, `W61`, `Y07`, `Y08`, `Y21` | -`X40` in 2011 + `Z77` in 2012 is what makes the recipe bridge testable in the fixture. +This reaches four of the five subtypes — `general` (W), `employee_retirement` +(X/Z), `unemployment_trust` (Y07/Y08) and `workers_comp_trust` (Y21) — and +carries **both** wide→modern recipe bridges (`X40`→`Z77` and `X41`→`Z78`), so +the whole plan is testable offline. + +`other_insurance_trust` (`Y61`) is not present for Wisconsin in the fixture. No +test below depends on it; do not substitute a different government to reach it. + +Do **not** assert on `gov_name`. The fixture carries both `"WISCONSIN"` (from +`long`) and `"WISCONSIN STATE GOVT"` (from the xwalk), and the verb resolves +`COALESCE(xwalk_gov_name, gov_name)`. ## File Structure @@ -301,7 +315,7 @@ Add to `tests/testthat/test-balances.R`: test_that("cog_balances returns holdings for a government that has them", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", 2019) + r <- cog_balances("550000227544", 2019) expect_s3_class(r, "tbl_df") expect_true(nrow(r) > 0L) expect_true(all(c("year", "canonical_govid", "gov_name", "balance_subtype", @@ -316,7 +330,7 @@ test_that("cog_balances returns holdings for a government that has them", { test_that('category = "Fund Balances" is exactly the general family', { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", 2019, category = "Fund Balances") + r <- cog_balances("550000227544", 2019, category = "Fund Balances") expect_identical(unique(r$balance_subtype), "general") codes <- sort(unlist(strsplit(paste(r$codes_included, collapse = ","), ","))) expect_identical(codes, c("W01", "W31", "W61")) @@ -326,7 +340,7 @@ test_that('category = "Fund Balances" is exactly the general family', { test_that("no flow code can reach cog_balances", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", c(2011, 2012, 2019, 2020)) + r <- cog_balances("550000227544", c(2011, 2012, 2019, 2020)) got <- unique(unlist(strsplit(paste(r$codes_included, collapse = ","), ","))) # The expected set is read from the RAW corpus, never from the verb -- @@ -514,8 +528,8 @@ git commit -m "feat: cog_balances() core verb (#25)" test_that("per_capita divides holdings by population", { skip_if_no_corpus() with_fixture_corpus({ - plain <- cog_balances("010000226085", 2019, category = "Fund Balances") - pc <- cog_balances("010000226085", 2019, category = "Fund Balances", + plain <- cog_balances("550000227544", 2019, category = "Fund Balances") + pc <- cog_balances("550000227544", 2019, category = "Fund Balances", per_capita = TRUE) expect_true("amt_per_capita_nominal" %in% names(pc)) expect_true("pop_source" %in% names(pc)) @@ -527,7 +541,7 @@ test_that("per_capita divides holdings by population", { pop <- DBI::dbGetQuery(cog_open(), sprintf( "SELECT population FROM gov_population_yearly WHERE canonical_govid = %s AND year = 2019", - uscogdata:::.sql_lit_chr("010000226085") + uscogdata:::.sql_lit_chr("550000227544") ))$population expect_length(pop, 1L) expect_equal(pc$amt_per_capita_nominal, pc$amt_nominal / pop, @@ -541,7 +555,7 @@ test_that("per_capita divides holdings by population", { test_that("adjust_to_year adds real dollars", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", 2012, category = "Fund Balances", + r <- cog_balances("550000227544", 2012, category = "Fund Balances", adjust_to_year = 2020) expect_true("amt_real" %in% names(r)) # 2012 dollars inflated to 2020 must exceed nominal. @@ -609,7 +623,7 @@ git commit -m "feat: per_capita and adjust_to_year for cog_balances() (#25)" test_that("recipe bridges the wide era into the modern one", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", c(2011, 2012), + r <- cog_balances("550000227544", c(2011, 2012), recipe = "cash_securities_z77_wide") expect_identical(sort(r$year), c(2011L, 2012L)) @@ -630,7 +644,7 @@ test_that("recipe bridges the wide era into the modern one", { test_that("the FY2002 book-to-market basis change is disclosed on the recipe path", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", c(2011, 2012), + r <- cog_balances("550000227544", c(2011, 2012), recipe = "cash_securities_z77_wide") refs <- attr(r, "provenance")$series_break_refs # SB195 sits on fin_code X40; it can only fire where X40 is observed, @@ -639,10 +653,23 @@ test_that("the FY2002 book-to-market basis change is disclosed on the recipe pat }) }) +test_that("the second holdings bridge works too", { + skip_if_no_corpus() + with_fixture_corpus({ + # X41 -> Z78, the securities counterpart. Wisconsin carries X41 in 2011 + # and Z78 in 2012, so both legs are exercised. + r <- cog_balances("550000227544", c(2011, 2012), + recipe = "cash_securities_z78_wide") + codes <- attr(r, "provenance")$codes_summed$observed + expect_true(all(c("X41", "Z78") %in% codes)) + expect_identical(sort(r$year), c(2011L, 2012L)) + }) +}) + test_that("an unknown recipe id is rejected", { skip_if_no_corpus() with_fixture_corpus({ - expect_error(cog_balances("010000226085", 2019, recipe = "no_such_recipe")) + expect_error(cog_balances("550000227544", 2019, recipe = "no_such_recipe")) }) }) ``` @@ -735,7 +762,7 @@ git commit -m "feat: recipe= bridges the wide-era holdings series (#25)" test_that("balance_caveats is always present and flags the GAAP distinction", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", 2019) + r <- cog_balances("550000227544", 2019) cav <- attr(r, "provenance")$balance_caveats expect_false(is.null(cav)) expect_true(cav$not_gaap) @@ -745,7 +772,7 @@ test_that("balance_caveats is always present and flags the GAAP distinction", { test_that("coverage_window is computed from the corpus, not hardcoded", { skip_if_no_corpus() with_fixture_corpus({ - r <- cog_balances("010000226085", c(2011, 2012, 2019, 2020)) + r <- cog_balances("550000227544", c(2011, 2012, 2019, 2020)) cav <- attr(r, "provenance")$balance_caveats ds <- arrow::open_dataset( @@ -768,7 +795,7 @@ test_that("a request past a family's coverage window is flagged", { skip_if_no_corpus() with_fixture_corpus({ # employee_retirement stops at FY2016; 2019/2020 are past it. - r <- cog_balances("010000226085", c(2012, 2019)) + r <- cog_balances("550000227544", c(2012, 2019)) cav <- attr(r, "provenance")$balance_caveats expect_true("employee_retirement" %in% cav$truncated) }) @@ -777,8 +804,8 @@ test_that("a request past a family's coverage window is flagged", { test_that("the caveat message fires once per session", { skip_if_no_corpus() with_fixture_corpus({ - expect_message(cog_balances("010000226085", 2019), "not.*GAAP") - expect_no_message(cog_balances("010000226085", 2020)) + expect_message(cog_balances("550000227544", 2019), "not.*GAAP") + expect_no_message(cog_balances("550000227544", 2020)) }) }) ```