fix: cog_categories() surfaces balance subtypes and accepts type = "balance" #29

2026-08-03T12:02:39-04:00

jared commented

2026-08-03 12:02:39 -04:00

Found while implementing cog-api#26.

The balance work (#25) added category_type = "balance" rows to the corpus and cog_balances() to read them, but left cog_categories() — the discovery surface — unable to describe them:

subtype COALESCEd only spend_subtype and revenue_subtype, so every balance row returned subtype = NA
type rejected "balance", so there was no way to ask for the holdings taxonomy at all

Both matter downstream: cog-api derives its subtype vocabulary from cog_categories() (api/R/session.R, .known_subtypes()), so an NA subtype becomes an unusable API parameter. This blocks the /balances endpoint being able to validate or offer a subtype filter.

cog_balances() itself still takes no subtype argument — for holdings, category is a strict coarsening of balance_subtype — but the value belongs in the discovery surface regardless, and the roxygen now says so explicitly so the asymmetry is not mistaken for an oversight.

Test plan

Two new tests in tests/testthat/test-categories.R. Both failed before the fix (3 failures: NA subtypes, and type = "balance" aborting) and pass after.
The expected subtype set is read independently from summary_categories.parquet via DuckDB, not from the function under test.
Full suite 795 pass / 0 fail / 0 skip (was 788).
CI green.

Found while implementing `cog-api#26`. The balance work (#25) added `category_type = "balance"` rows to the corpus and `cog_balances()` to read them, but left `cog_categories()` — the discovery surface — unable to describe them: - `subtype` COALESCEd only `spend_subtype` and `revenue_subtype`, so every balance row returned `subtype = NA` - `type` rejected `"balance"`, so there was no way to ask for the holdings taxonomy at all Both matter downstream: `cog-api` derives its subtype vocabulary from `cog_categories()` (`api/R/session.R`, `.known_subtypes()`), so an NA subtype becomes an unusable API parameter. This blocks the `/balances` endpoint being able to validate or offer a `subtype` filter. `cog_balances()` itself still takes no `subtype` argument — for holdings, `category` is a strict coarsening of `balance_subtype` — but the value belongs in the discovery surface regardless, and the roxygen now says so explicitly so the asymmetry is not mistaken for an oversight. ## Test plan - [x] Two new tests in `tests/testthat/test-categories.R`. Both failed before the fix (3 failures: NA subtypes, and `type = "balance"` aborting) and pass after. - [x] The expected subtype set is read independently from `summary_categories.parquet` via DuckDB, not from the function under test. - [x] Full suite **795 pass / 0 fail / 0 skip** (was 788). - [ ] CI green.

jared added 1 commit 2026-08-03 12:02:39 -04:00

fix: cog_categories() surfaces balance subtypes and accepts type = "balance"

R-CMD-check / check (pull_request) Successful in 3m39s

Details

R-CMD-check / check (push) Successful in 3m39s

Details

da726a61f6

The balance work added category_type = "balance" rows to the corpus and
cog_balances() to read them, but left cog_categories() -- the discovery
surface -- unable to describe them:

- subtype COALESCEd only spend_subtype and revenue_subtype, so every balance
  row came back with subtype = NA
- type rejected "balance", so there was no way to ask for the holdings
  taxonomy at all

Both matter downstream: cog-api derives its subtype vocabulary from
cog_categories(), so an NA subtype becomes an unusable API parameter. Found
while implementing cog-api#26.

Note cog_balances() itself still takes no subtype argument -- for holdings
category is a strict coarsening of balance_subtype -- but the value belongs
in the discovery surface regardless.

Tests read the expected subtype set independently from the crosswalk parquet
rather than from the function under test.

jared merged commit 0a6d878a36 into main

2026-08-03 12:20:11 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Civilytics/uscogdata#29