R/provenance.R

@@ -6,6 +6,8 @@
                               per_capita, adjust_to_year, result, sql,
                               subtype_col, basis = NA_character_,
                               basis_note = NA_character_,
+                              expenditure_concept = "direct",
+                              expenditure_concept_note = NA_character_,
                               harmonization = NULL, recipe = NULL,
                               suggestions = list()) {
   manifest <- .uscogdata_env$manifest
@@ -51,6 +53,8 @@
     category = category,
     basis = basis,
     basis_note = basis_note,
+    expenditure_concept = expenditure_concept,
+    expenditure_concept_note = expenditure_concept_note,
     harmonization = harmonization %||% list(
       applied = FALSE, na_rows_excluded = 0L, na_amount_excluded = 0,
       note = NA_character_

R/spending.R

@@ -220,6 +220,14 @@ cog_spending <- function(govid, years, category = NULL,
     suggestions <- .build_suggestions(con, govid, years, category, result, resolved$basis)
   }
 
+  # Determine expenditure_concept_note: only non-empty for "total", explains
+  # how the IG leg was assembled from legacy-era aggregates.
+  expenditure_concept_note_for_prov <- if (identical(expenditure_concept, "total")) {
+    "Total = Direct + intergovernmental (M to local govts + L to state govts). Legacy-era IG is assembled from aggregate-flagged rows, which are year-disjoint from their modern leaf components; the L-- family total is excluded."
+  } else {
+    NA_character_
+  }
+
   prov <- .build_provenance(
     verb           = verb,
     call           = call,
@@ -233,6 +241,8 @@ cog_spending <- function(govid, years, category = NULL,
     subtype_col    = subtype_col,
     basis          = basis_for_prov,
     basis_note     = basis_note_for_prov,
+    expenditure_concept = expenditure_concept,
+    expenditure_concept_note = expenditure_concept_note_for_prov,
     harmonization  = harmonization,
     recipe         = recipe_block,
     suggestions    = suggestions

inst/schemas/provenance-v1.json

@@ -12,6 +12,15 @@
     "category":       { "type": ["string", "array", "null"] },
     "basis":          { "type": ["string", "null"] },
     "basis_note":     { "type": ["string", "null"] },
+    "expenditure_concept": {
+      "type": "string",
+      "enum": ["direct", "total"],
+      "description": "Which spending concept produced this result. 'direct' is the government's own E/F/G spending; 'total' adds its intergovernmental payments (M to local governments, L to state governments). Only 'direct' is valid for results combined across governments."
+    },
+    "expenditure_concept_note": {
+      "type": ["string", "null"],
+      "description": "How the intergovernmental leg was assembled; null for 'direct'."
+    },
     "harmonization":  { "type": "object" },
     "recipe":         { "type": ["object", "null"] },
     "suggestions":    { "type": "array" },

tests/testthat/test-expenditure-concept.R

@@ -244,3 +244,23 @@ test_that("both cross-government verbs still accept the direct default", {
                      category = "Police", years = 2019)
   )
 })
+
+test_that("provenance always records the expenditure concept", {
+  d <- cog_spending("010000226085", years = 2019, category = "Police")
+  t <- cog_spending("010000226085", years = 2019, category = "Police",
+                    expenditure_concept = "total")
+  expect_equal(attr(d, "provenance")$expenditure_concept, "direct")
+  expect_equal(attr(t, "provenance")$expenditure_concept, "total")
+  # The note explains the non-obvious part: how legacy IG was assembled.
+  expect_true(nzchar(attr(t, "provenance")$expenditure_concept_note))
+  expect_true(is.na(attr(d, "provenance")$expenditure_concept_note) ||
+              !nzchar(attr(d, "provenance")$expenditure_concept_note))
+})
+
+test_that("the provenance schema documents expenditure_concept", {
+  sch <- jsonlite::fromJSON(
+    system.file("schemas", "provenance-v1.json", package = "uscogdata"),
+    simplifyVector = FALSE
+  )
+  expect_true("expenditure_concept" %in% names(sch$properties))
+})