feat: package skeleton — DESCRIPTION, NAMESPACE, session/manifest/cache/views

Minimal skeleton for uscogdata v0.1. Internal session layer with lazy
cog_open(), manifest fetch+validate+cache, view registration placeholder.
Depends on DuckDB >=1.0, httr2, jsonlite. inst/schemas/provenance-v1.json
ships the structured provenance JSON Schema.

R/cache.R

@@ -0,0 +1,6 @@
+# R/cache.R
+# Local partition cache; SHA-based invalidation.
+# Phase N v0.1 implementation: DuckDB httpfs handles actual reads directly
+# from Nextcloud; cache_dir holds only manifest.json. Richer partition
+# caching (pre-fetch hot partitions) is a v0.2 feature.
+# Stub here for cog_mirror to compose against.

R/config.R

@@ -0,0 +1,29 @@
+# R/config.R
+
+#' Package-private mutable state
+#' @noRd
+.uscogdata_env <- new.env(parent = emptyenv())
+
+.uscogdata_defaults <- list(
+  url               = "https://cloud.civilytics.org/s/REPLACE_WITH_SHARE_TOKEN/download/",
+  cache_dir         = NULL,
+  manifest_ttl_secs = 3600L
+)
+
+#' Resolve a config value: env var > option > default
+#' @noRd
+.cfg <- function(key) {
+  env_var <- paste0("USCOGDATA_", toupper(key))
+  v <- Sys.getenv(env_var, unset = NA)
+  if (!is.na(v) && nzchar(v)) return(v)
+  opt <- getOption(paste0("uscogdata.", key), default = NULL)
+  if (!is.null(opt)) return(opt)
+  .uscogdata_defaults[[key]]
+}
+
+.resolve_url <- function() .cfg("url")
+
+.resolve_cache_dir <- function() {
+  v <- .cfg("cache_dir")
+  if (is.null(v)) tools::R_user_dir("uscogdata", "cache") else v
+}

R/manifest.R

@@ -0,0 +1,40 @@
+# R/manifest.R
+
+#' Fetch manifest.json from URL, cache locally, validate TTL.
+#' @noRd
+.fetch_or_cache_manifest <- function(url, cache_dir) {
+  cache_path <- file.path(cache_dir, "manifest.json")
+  ttl <- as.integer(.cfg("manifest_ttl_secs"))
+
+  needs_fetch <- !file.exists(cache_path) ||
+                 difftime(Sys.time(), file.info(cache_path)$mtime, units = "secs") > ttl
+
+  if (needs_fetch) {
+    resp <- httr2::request(paste0(url, "manifest.json")) |>
+      httr2::req_error(is_error = function(r) httr2::resp_status(r) >= 400) |>
+      httr2::req_perform()
+    writeLines(httr2::resp_body_string(resp), cache_path)
+  }
+
+  jsonlite::fromJSON(cache_path, simplifyVector = FALSE)
+}
+
+#' @noRd
+.validate_schema <- function(manifest, expected_version) {
+  if (manifest$schema_version != expected_version) {
+    cli::cli_abort(c(
+      "Corpus schema version mismatch.",
+      x = "Package expects schema_version = {expected_version}; corpus has {manifest$schema_version}.",
+      i = "Update uscogdata (install.packages or pak::pkg_install) or re-publish corpus."
+    ))
+  }
+}
+
+#' @noRd
+.validate_scope <- function(manifest) {
+  included <- manifest$scope$gov_types_included
+  .uscogdata_env$scope_included <- included
+  invisible(NULL)
+}
+
+`%||%` <- function(a, b) if (is.null(a) || (length(a) == 1 && is.na(a))) b else a

R/session.R

@@ -0,0 +1,43 @@
+# R/session.R
+
+#' Internal: open session, register views, cache manifest.
+#' Not exported. Called lazily by verbs via .ensure_session().
+#' @noRd
+cog_open <- function(url = .resolve_url(),
+                     cache_dir = .resolve_cache_dir()) {
+  if (!dir.exists(cache_dir)) dir.create(cache_dir, recursive = TRUE)
+
+  con <- DBI::dbConnect(duckdb::duckdb())
+  DBI::dbExecute(con, "INSTALL httpfs; LOAD httpfs;")
+
+  manifest <- .fetch_or_cache_manifest(url, cache_dir)
+  .validate_schema(manifest, expected_version = 2L)
+  .validate_scope(manifest)
+
+  .register_views(con, url, manifest)
+
+  .uscogdata_env$con       <- con
+  .uscogdata_env$manifest  <- manifest
+  .uscogdata_env$url       <- url
+  .uscogdata_env$cache_dir <- cache_dir
+
+  invisible(con)
+}
+
+#' @noRd
+.ensure_session <- function() {
+  if (is.null(.uscogdata_env$con) ||
+      !DBI::dbIsValid(.uscogdata_env$con)) {
+    cog_open()
+  }
+  .uscogdata_env$con
+}
+
+#' @noRd
+cog_close <- function() {
+  if (!is.null(.uscogdata_env$con) && DBI::dbIsValid(.uscogdata_env$con)) {
+    DBI::dbDisconnect(.uscogdata_env$con, shutdown = TRUE)
+  }
+  .uscogdata_env$con      <- NULL
+  .uscogdata_env$manifest <- NULL
+}

R/views.R

@@ -0,0 +1,13 @@
+# R/views.R
+
+#' Register DuckDB views from inst/sql/ SQL files
+#' @noRd
+.register_views <- function(con, url, manifest) {
+  sql_dir <- system.file("sql", package = "uscogdata")
+  files   <- list.files(sql_dir, pattern = "\\.sql$", full.names = TRUE)
+  for (f in files) {
+    sql <- paste(readLines(f, warn = FALSE), collapse = "\n")
+    sql <- gsub("\\{url\\}", url, sql, fixed = FALSE)
+    DBI::dbExecute(con, sql)
+  }
+}

R/zzz.R

@@ -0,0 +1,9 @@
+# R/zzz.R
+
+.onLoad <- function(libname, pkgname) {
+  invisible(NULL)
+}
+
+.onUnload <- function(libpath) {
+  cog_close()
+}