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).
This commit is contained in:
2026-04-24 09:49:09 -04:00
parent cea7a241c5
commit c682e6547d
12 changed files with 672 additions and 1 deletions
+23
View File
@@ -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).
}