From e635a1fc9efdca21099d5c452a763511a6ef4adc Mon Sep 17 00:00:00 2001
From: Jared Knowles <jared@civilytics.com>
Date: Sat, 11 Jul 2026 09:31:33 -0400
Subject: [PATCH] feat!: require corpus schema_version 4 (Phase P canonical
 ids)

BREAKING CHANGE: canonical_govid is now uniformly 12 characters across
every vintage; corpora built against schema_version 3 are rejected.
Bumps MinCorpusSchema/MaxCorpusSchema to 4 and expected_version in
cog_open(). canonical_fips_xwalk grows to the 14-column Phase P master
schema (adds legacy_govs_id, census_geoid, id_source; confidence is
renamed to pop_confidence); .empty_xwalk_tibble() is rewritten to match.
---
 DESCRIPTION |  4 ++--
 NEWS.md     | 20 ++++++++++++++++++++
 R/search.R  |  7 ++++---
 R/session.R |  2 +-
 4 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index f91acc5..498ff41 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -31,5 +31,5 @@ Suggests:
 Config/testthat/edition: 3
 VignetteBuilder: knitr
 RoxygenNote: 7.3.3
-MinCorpusSchema: 3
-MaxCorpusSchema: 3
+MinCorpusSchema: 4
+MaxCorpusSchema: 4
diff --git a/NEWS.md b/NEWS.md
index 375f877..2f171b0 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,25 @@
 # uscogdata 0.1.0 (development)
 
+## Breaking: corpus schema_version 4 (Phase P canonical ids)
+
+* The package now requires corpus `schema_version = 4` (`MinCorpusSchema` /
+  `MaxCorpusSchema` in `DESCRIPTION` are both `4`); older corpora built
+  against schema 3 are rejected by `cog_open()` with a clear version-mismatch
+  error. `canonical_govid` is now uniformly 12 characters across every
+  vintage the corpus covers (previously a mix of 9-char legacy ids and
+  12-char FIPS ids depending on source year) — **every hardcoded
+  `canonical_govid` literal from a pre-Phase-P corpus is now invalid** and
+  must be re-resolved via `cog_gov_search()` or the new `canonical_alias`
+  lookup table. `canonical_fips_xwalk` gains four columns
+  (`legacy_govs_id`, `census_geoid`, `id_source`; `confidence` is renamed to
+  `pop_confidence`) and a companion `canonical_alias` table ships in the
+  corpus for mapping legacy/alternate ids onto the current canonical
+  namespace. The bundled fixture corpus (`inst/extdata/fixture_corpus/`) has
+  been regenerated against the Phase P publish tree, now ships the full
+  `canonical_fips_xwalk` and `canonical_alias` master tables alongside the
+  2019-2020 long partitions, and is reproducible via
+  `data-raw/regenerate_fixture_corpus.R`.
+
 ## Clearer errors when `USCOGDATA_URL` is unconfigured or returns non-JSON
 
 * `cog_open()` now aborts with the `uscogdata_url_not_configured` error
diff --git a/R/search.R b/R/search.R
index d2b78d6..4a28eb7 100644
--- a/R/search.R
+++ b/R/search.R
@@ -126,9 +126,10 @@ cog_gov_search <- function(name = NULL, state = NULL, type = NULL) {
     canonical_govid = character(0), gov_name = character(0),
     govs_type = integer(0), type_label = character(0),
     fips_state = character(0), fips_county = character(0),
-    fips_place = character(0), first_year = integer(0),
-    last_year = integer(0), population_acs = integer(0),
-    confidence = character(0)
+    fips_place = character(0), legacy_govs_id = character(0),
+    first_year = integer(0), last_year = integer(0),
+    census_geoid = character(0), population_acs = integer(0),
+    pop_confidence = character(0), id_source = character(0)
   )
 }
 
diff --git a/R/session.R b/R/session.R
index 422469e..1e9f313 100644
--- a/R/session.R
+++ b/R/session.R
@@ -12,7 +12,7 @@ cog_open <- function(url = .resolve_url(),
   DBI::dbExecute(con, "INSTALL httpfs; LOAD httpfs;")
 
   manifest <- .fetch_or_cache_manifest(url, cache_dir)
-  .validate_schema(manifest, expected_version = 3L)
+  .validate_schema(manifest, expected_version = 4L)
   .validate_scope(manifest)
 
   .register_views(con, url, manifest)