feat: cog_gov_search + cog_mirror + scope-aware verb behavior

Three pieces:

1. cog_gov_search: name/state/type search over canonical_fips_xwalk
   for resolving human-readable place names into canonical_govids.
   Accepts USPS abbrev ('FL') or FIPS int (12) for state; integer
   0-3 or name ('state','county','city','township') for type. Types
   4/5 emit an explanatory cli message and return an empty tibble
   (v0.1 corpus excludes them). USPS<->FIPS table hardcoded with
   50 states + DC + territories; FIPS 66 = GU (not GA).

2. cog_mirror: downloads manifest-listed files to a local directory
   with SHA-256 idempotency (files with matching hash return status
   'cached'). Supports HTTP and local-path fixture URLs. Round-trip
   test: mirror + re-open against the mirror + query Broward 2020
   returns identical results.

3. Scope-aware verbs: .check_govids_in_scope() helper in session.R
   queries canonical_fips_xwalk for the requested govids, emits a
   cli_inform listing any missing ones, and records the found/missing
   sets under provenance$scope. Wired into cog_spending (and
   transitively into cog_revenue, cog_geographic_rollup,
   cog_peer_compare via their cog_spending calls).

Also: dropped dbplyr from Imports (unused).

Tests: +29 (22 search + 12 mirror - 5 refactored) / 159 total pass.
devtools::check() now clean: 0E / 0W / 0N.

tests/testthat/test-mirror.R

@@ -0,0 +1,67 @@
+test_that("cog_mirror copies manifest + metadata files", {
+  skip_if_no_corpus()
+  tmp <- tempfile("uscogmirror_"); dir.create(tmp)
+  on.exit(unlink(tmp, recursive = TRUE))
+
+  r <- cog_mirror(tmp, include = "metadata", progress = FALSE)
+  expect_s3_class(r, "tbl_df")
+  expect_true(file.exists(file.path(tmp, "manifest.json")))
+  expect_true(file.exists(file.path(tmp, "data/canonical_fips_xwalk.parquet")))
+  expect_true(file.exists(file.path(tmp, "data/summary_categories.parquet")))
+  expect_true(all(r$status == "downloaded"))
+  expect_true(all(c("path", "sha256", "size_bytes", "status") %in% names(r)))
+})
+
+test_that("cog_mirror is idempotent when SHA matches (status = 'cached')", {
+  skip_if_no_corpus()
+  tmp <- tempfile("uscogmirror_"); dir.create(tmp)
+  on.exit(unlink(tmp, recursive = TRUE))
+
+  cog_mirror(tmp, include = "metadata", progress = FALSE)
+  r2 <- cog_mirror(tmp, include = "metadata", progress = FALSE)
+  expect_true(all(r2$status == "cached"))
+})
+
+test_that("cog_mirror overwrite = TRUE re-copies even when SHA matches", {
+  skip_if_no_corpus()
+  tmp <- tempfile("uscogmirror_"); dir.create(tmp)
+  on.exit(unlink(tmp, recursive = TRUE))
+
+  cog_mirror(tmp, include = "metadata", progress = FALSE)
+  r3 <- cog_mirror(tmp, include = "metadata", progress = FALSE, overwrite = TRUE)
+  expect_true(all(r3$status == "downloaded"))
+})
+
+test_that("cog_mirror verifies sha256 against manifest", {
+  skip_if_no_corpus()
+  tmp <- tempfile("uscogmirror_"); dir.create(tmp)
+  on.exit(unlink(tmp, recursive = TRUE))
+
+  r <- cog_mirror(tmp, include = "metadata", progress = FALSE)
+  for (i in seq_len(nrow(r))) {
+    got <- digest::digest(file.path(tmp, r$path[i]),
+                          algo = "sha256", file = TRUE)
+    expect_equal(got, r$sha256[i])
+  }
+})
+
+test_that("cog_mirror reads back via a fresh session against the mirror", {
+  skip_if_no_corpus()
+  tmp <- tempfile("uscogmirror_"); dir.create(tmp)
+  on.exit(unlink(tmp, recursive = TRUE))
+
+  cog_mirror(tmp, include = c("long", "metadata"), progress = FALSE)
+
+  # Re-open against the local mirror and run a query.
+  old_url <- getOption("uscogdata.url")
+  on.exit({
+    cog_close()
+    options(uscogdata.url = old_url)
+  }, add = TRUE)
+  cog_close()
+  options(uscogdata.url = paste0(normalizePath(tmp), "/"))
+
+  r <- cog_spending("101006006", 2020L, "Corrections")
+  expect_gt(nrow(r), 0L)
+  expect_equal(unique(r$canonical_govid), "101006006")
+})

tests/testthat/test-search.R

@@ -0,0 +1,74 @@
+test_that("cog_gov_search by name pattern returns matches", {
+  skip_if_no_corpus()
+  r <- cog_gov_search("^BROWARD")
+  expect_s3_class(r, "tbl_df")
+  expect_true(all(grepl("^BROWARD", r$gov_name)))
+  expect_true("canonical_govid" %in% names(r))
+})
+
+test_that("cog_gov_search case-insensitive", {
+  skip_if_no_corpus()
+  r <- cog_gov_search("broward")
+  expect_gt(nrow(r), 0L)
+})
+
+test_that("cog_gov_search by state abbreviation", {
+  skip_if_no_corpus()
+  r <- cog_gov_search(state = "FL", type = 1L)
+  expect_true(all(r$fips_state == "12"))
+  expect_true(all(r$govs_type == 1L))
+})
+
+test_that("cog_gov_search accepts FIPS int for state", {
+  skip_if_no_corpus()
+  r <- cog_gov_search(state = 12, type = "county")
+  expect_true(all(r$fips_state == "12"))
+  expect_true(all(r$govs_type == 1L))
+})
+
+test_that("cog_gov_search accepts type as name string", {
+  skip_if_no_corpus()
+  for (pair in list(c("state", 0), c("county", 1), c("city", 2), c("township", 3))) {
+    r <- cog_gov_search(type = pair[1])
+    expect_true(all(r$govs_type == as.integer(pair[2])))
+  }
+})
+
+test_that("cog_gov_search for excluded types emits message and returns empty", {
+  skip_if_no_corpus()
+  expect_message(
+    r <- cog_gov_search(type = 4L),
+    "v0.1|excluded"
+  )
+  expect_equal(nrow(r), 0L)
+  expect_true("canonical_govid" %in% names(r))
+  expect_message(
+    r2 <- cog_gov_search(type = "special_district"),
+    "v0.1|excluded"
+  )
+  expect_equal(nrow(r2), 0L)
+})
+
+test_that("cog_gov_search combining filters", {
+  skip_if_no_corpus()
+  r <- cog_gov_search("BROWARD", state = "FL")
+  expect_true(all(grepl("BROWARD", r$gov_name)))
+  expect_true(all(r$fips_state == "12"))
+})
+
+test_that("cog_gov_search sorts by population desc", {
+  skip_if_no_corpus()
+  r <- cog_gov_search(state = "FL", type = 2L)
+  nonNA <- r$population_acs[!is.na(r$population_acs)]
+  expect_true(all(diff(nonNA) <= 0))
+})
+
+test_that("cog_gov_search rejects unknown type string", {
+  expect_error(cog_gov_search(type = "galaxy"), "Unknown type")
+})
+
+test_that("cog_gov_search with no filters returns full registry", {
+  skip_if_no_corpus()
+  r <- cog_gov_search()
+  expect_gt(nrow(r), 1000L)
+})

tests/testthat/test-spending.R

@@ -50,14 +50,29 @@ test_that("cog_spending with per_capita + adjust_to_year adds all columns", {
                   names(r)))
 })
 
-test_that("cog_spending for unknown govid returns empty tibble", {
+test_that("cog_spending for unknown govid returns empty tibble + informs", {
   skip_if_no_corpus()
-  r <- cog_spending("XXXINVALID", 2020L, "Corrections")
+  expect_message(
+    r <- cog_spending("XXXINVALID", 2020L, "Corrections"),
+    "not found|v0.1"
+  )
   expect_s3_class(r, "tbl_df")
   expect_equal(nrow(r), 0L)
   expect_true("notes" %in% names(r))
-  # provenance still attached
-  expect_false(is.null(attr(r, "provenance")))
+  prov <- attr(r, "provenance")
+  expect_false(is.null(prov))
+  expect_equal(prov$scope$govids_missing, "XXXINVALID")
+  expect_equal(length(prov$scope$govids_found), 0L)
+})
+
+test_that("cog_spending records found + missing govids in provenance", {
+  skip_if_no_corpus()
+  suppressMessages(
+    r <- cog_spending(c("101006006", "XXXINVALID"), 2020L, "Corrections")
+  )
+  prov <- attr(r, "provenance")
+  expect_equal(sort(prov$scope$govids_found), "101006006")
+  expect_equal(sort(prov$scope$govids_missing), "XXXINVALID")
 })
 
 test_that("cog_spending result has provenance attribute matching schema", {