feat: cog_geographic_rollup

Wraps cog_spending across a named list of state/county/city layers,
tagging each row with its `layer` and attaching a scope_note that
documents geographic-scope caveats (state totals are statewide, county
totals include areas outside a listed city, city proper excludes
special districts). Per-capita uses each layer's own population from
the canonical_fips_xwalk.

Provenance is inherited from cog_spending but rewritten to reflect
the outer verb (verb, call, layers).

Tests: 19 new / 99 total pass. devtools::check() 0E/0W/2N.

man/cog_geographic_rollup.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/rollup.R
+\name{cog_geographic_rollup}
+\alias{cog_geographic_rollup}
+\title{Aggregate spending across state/county/city layers for a place}
+\usage{
+cog_geographic_rollup(
+  govids,
+  category,
+  years,
+  per_capita = FALSE,
+  adjust_to_year = NULL
+)
+}
+\arguments{
+\item{govids}{Named list with any non-empty subset of elements named
+`state`, `county`, `city`. Each element is a character vector of
+`canonical_govid` values. At least one layer required.}
+
+\item{category}{Single category name or character vector (passed through
+to [cog_spending()]).}
+
+\item{years}{Integer vector of years.}
+
+\item{per_capita}{If `TRUE`, per-capita uses each layer's own population
+from `canonical_fips_xwalk.population_acs`.}
+
+\item{adjust_to_year}{Integer base year for CPI-U conversion, or `NULL`.}
+}
+\value{
+Tibble with columns `year`, `layer`, `canonical_govid`, `gov_name`,
+  `spend_subtype`, `category`, `amt_nominal`, optional `amt_real` /
+  `amt_per_capita_nominal` / `amt_per_capita_real`, `codes_included`,
+  `aggregate_fallback`, `scope_note`, `notes`. Carries a `provenance`
+  attribute with `verb = "cog_geographic_rollup"` and `layers`.
+}
+\description{
+Wraps [cog_spending()], tags each row with its layer, and attaches a
+human-readable `scope_note` documenting geographic-scope caveats (e.g.
+"county totals include areas outside the listed city"). Useful for
+"place portraits" that compare a city to the surrounding county and
+containing state on one set of axes.
+}