feat: cog_spending + cog_revenue + cog_explain

Three core query verbs over the spending_annotated / revenue_annotated
DuckDB views. Each verb accepts vector govid, vector years, optional
category filter, per_capita flag, and adjust_to_year for CPI-U
real-dollar conversion (bundled index).

Amounts are returned in full USD (SUM(amt) * 1000) so callers can
freely rescale to millions/billions. The $1,000s -> $USD conversion
is recorded in provenance$transformations$units_conversion.

Every result carries an attr(., "provenance") list matching
inst/schemas/provenance-v1.json. cog_explain() prints the structured
form via cli or returns the raw list for MCP/JSON consumers.

Also: .fetch_or_cache_manifest() now handles local fixture paths so
tests can point USCOGDATA_FIXTURE_URL at the pipeline publish_cache/
without a working HTTP server.

Tests: 80 pass / 0 fail. devtools::check() 0E/0W/2N (both notes
pre-existing / environmental).

man/cog_explain.Rd

@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/explain.R
+\name{cog_explain}
+\alias{cog_explain}
+\title{Explain a verb result's provenance}
+\usage{
+cog_explain(result, format = c("print", "list"))
+}
+\arguments{
+\item{result}{A tibble returned by a `cog_*` verb.}
+
+\item{format}{`"print"` (default) for a human-readable cli summary;
+returns `result` invisibly for chaining. `"list"` returns the raw
+provenance list (identical to `attr(result, "provenance")`).}
+}
+\value{
+Either `result` (invisibly) or the provenance list.
+}
+\description{
+Prints the structured provenance attached to a tibble returned by any
+`cog_*` verb, or returns it as a list for downstream use (MCP tools,
+dashboards, JSON export).
+}

man/cog_revenue.Rd

@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/revenue.R
+\name{cog_revenue}
+\alias{cog_revenue}
+\title{Summarized revenue by category}
+\usage{
+cog_revenue(
+  govid,
+  years,
+  category = NULL,
+  per_capita = FALSE,
+  adjust_to_year = NULL
+)
+}
+\arguments{
+\item{govid}{Character vector of `canonical_govid` values.}
+
+\item{years}{Integer vector of years.}
+
+\item{category}{Character vector of category names (from
+`summary_categories.category`), or `NULL` for all categories.}
+
+\item{per_capita}{If `TRUE`, adds `amt_per_capita_nominal` (and
+`amt_per_capita_real` when `adjust_to_year` is set) using
+`population_acs` from the canonical xwalk.}
+
+\item{adjust_to_year}{Integer base year for CPI-U real-dollar conversion,
+or `NULL` for nominal only.}
+}
+\value{
+Tibble with columns `year`, `canonical_govid`, `gov_name`,
+  `revenue_subtype`, `category`, `amt_nominal`, optional `amt_real`,
+  optional `amt_per_capita_nominal`, optional `amt_per_capita_real`,
+  `codes_included`, `aggregate_fallback`, `notes`.
+}
+\description{
+Mirror of [cog_spending()] for revenue categories. One row per
+`(year, canonical_govid, revenue_subtype, category)`. Amounts are returned
+in **full U.S. dollars** (raw Census values are in $1,000s; this verb
+multiplies by 1000 and records the conversion in `provenance`).
+}

man/cog_spending.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/spending.R
+\name{cog_spending}
+\alias{cog_spending}
+\title{Summarized spending by category}
+\usage{
+cog_spending(
+  govid,
+  years,
+  category = NULL,
+  per_capita = FALSE,
+  adjust_to_year = NULL
+)
+}
+\arguments{
+\item{govid}{Character vector of `canonical_govid` values.}
+
+\item{years}{Integer vector of years.}
+
+\item{category}{Character vector of category names (from
+`summary_categories.category`), or `NULL` for all categories.}
+
+\item{per_capita}{If `TRUE`, adds `amt_per_capita_nominal` (and
+`amt_per_capita_real` when `adjust_to_year` is set) using
+`population_acs` from the canonical xwalk.}
+
+\item{adjust_to_year}{Integer base year for CPI-U real-dollar conversion,
+or `NULL` for nominal only.}
+}
+\value{
+Tibble with columns `year`, `canonical_govid`, `gov_name`,
+  `spend_subtype`, `category`, `amt_nominal`, optional `amt_real`,
+  optional `amt_per_capita_nominal`, optional `amt_per_capita_real`,
+  `codes_included`, `aggregate_fallback`, `notes`. Carries a `provenance`
+  attribute matching `inst/schemas/provenance-v1.json`.
+}
+\description{
+One row per `(year, canonical_govid, spend_subtype, category)`. Amounts are
+returned in **full U.S. dollars** (the raw corpus stores them in $1,000s;
+this verb multiplies by 1000 so downstream code can freely rescale to
+millions/billions). The conversion is recorded in the provenance attribute
+under `transformations$units_conversion`.
+}