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)) }) }) ```