diff --git a/.Rbuildignore b/.Rbuildignore
index 481c3ac..786f647 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -16,3 +16,4 @@
 ^vignettes/precompile\.R$
 ^reviews$
 ^\.claude$
+\.qmd$
diff --git a/R/get_preliminary_damage_assessments.R b/R/get_preliminary_damage_assessments.R
index a12b256..79e1b94 100644
--- a/R/get_preliminary_damage_assessments.R
+++ b/R/get_preliminary_damage_assessments.R
@@ -1,25 +1,7 @@
 #' Derive collision-free local filenames for a set of PDA report URLs
 #'
-#' The last path segment of each URL is percent-decoded and stripped of
-#' characters that cannot appear in a Windows filename, which produces a
-#' readable local name. That transformation is lossy, so two different URLs can
-#' in principle reduce to the same name; where that happens, a short hash of the
-#' full URL is appended to each of the colliding names so that both reports are
-#' kept rather than one silently overwriting or being skipped past the other.
-#'
-#' The suffix is a hash of the URL rather than a running `_1`, `_2` counter for
-#' two reasons. First, it depends only on the URL, so a given report always
-#' resolves to the same filename and the `file.exists()` check in `save_pdf()`
-#' still recognizes it as already downloaded on a later run -- a counter
-#' assigned in encounter order would change between runs and re-download the
-#' whole archive. Second, FEMA's own filenames already use a `_0`/`_1` suffix to
-#' distinguish their duplicates (72 of the currently cached files do), so a
-#' counter would be indistinguishable from the source naming.
-#'
-#' Collisions are resolved across the complete set of URLs passed in, so
-#' `scrape_pda_pdfs()` must collect every listing page before calling this;
-#' resolving against a partial set could assign a name that a later page's URL
-#' also claims.
+#' File names can have tricky characters, including escaped/special characters
+#' derived from non-ASCI text. This handles that complexity.
 #'
 #' @param urls A character vector of PDF URLs.
 #'
@@ -31,20 +13,15 @@ resolve_pdf_destinations = function(urls) {
   destinations1 = tibble::tibble(url = unique(urls)) %>%
     dplyr::mutate(
       base_name = url %>%
-        ## drop any query string or fragment, which would otherwise survive into
-        ## the filename ("report.pdf?v=2" -> "report?v=2.pdf", which is not a
-        ## legal Windows filename and fails to download at all)
+        ## a query string or fragment left in place produces an illegal Windows
+        ## filename ("report.pdf?v=2" -> "report?v=2.pdf") that cannot be written
         stringr::str_remove("[?#].*$") %>%
         stringr::str_extract("[^/]+$") %>%
         curl::curl_unescape() %>%
-        ## anchored so only a trailing extension is removed, not every
-        ## occurrence of ".pdf" in the name
         stringr::str_remove(stringr::regex("\\.pdf$", ignore_case = TRUE)) %>%
         stringr::str_replace_all("[<>:\"/\\\\|?*]", "_") %>%
         stringr::str_remove_all("[[:cntrl:]]") %>%
         stringr::str_squish() %>%
-        ## decoded "%20" would otherwise leave literal spaces in the path; no
-        ## currently cached file contains one, so this does not rename anything
         stringr::str_replace_all("\\s+", "_")) %>%
     dplyr::add_count(base_name, name = "base_name_count") %>%
     dplyr::mutate(
@@ -58,12 +35,17 @@ resolve_pdf_destinations = function(urls) {
         stringr::str_c(base_name, ".pdf")))
 
   if (any(destinations1$needs_hash)) {
+    is_empty_name = is.na(destinations1$base_name) | destinations1$base_name == ""
+    collided = destinations1$needs_hash & !is_empty_name
+
     message(
       stringr::str_c(
         sum(destinations1$needs_hash),
-        " report URL(s) reduced to a filename already claimed by a different ",
-        "URL; a URL hash was appended so that every report is retained. ",
-        "Affected: ",
+        " report URL(s) were given a URL hash so that every report is retained: ",
+        sum(collided),
+        " reduced to a filename already claimed by a different URL, and ",
+        sum(is_empty_name),
+        " reduced to no filename at all. Affected: ",
         stringr::str_c(
           destinations1$destination_file[destinations1$needs_hash],
           collapse = ", "))) }
@@ -71,15 +53,22 @@ resolve_pdf_destinations = function(urls) {
   destinations1 %>% dplyr::select(url, destination_file)
 }
 
-#' Download a PDF from a URL and verify that a PDF is what arrived
+#' The browser identity FEMA's site requires
+#'
+#' @return A length-one character `User-Agent` string.
+#' @noRd
+browser_user_agent = function() {
+  stringr::str_c(
+    "Mozilla/5.0 (Linux; Android 11; SAMSUNG SM-G973U) AppleWebKit/537.36 ",
+    "(KHTML, like Gecko) SamsungBrowser/14.2 Chrome/87.0.4280.141 Mobile ",
+    "Safari/537.36")
+}
+
+#' Download a PDF from a URL and verify
 #'
 #' A download is kept only if the resulting file begins with the `%PDF` magic
 #' number and exceeds `minimum_bytes`. Anything else -- an HTML error page served
-#' with a 200 status, a truncated transfer -- is deleted rather than left on
-#' disk. This matters because the cache check is the file's existence: a bad file
-#' that stayed would never be retried on a later run, turning one transient
-#' failure into a permanent hole in the archive that looks no different from a
-#' complete one. Deleting it means the next run downloads it again.
+#' with a 200 status, a truncated transfer -- is deleted.
 #'
 #' @param url URL to the pdf.
 #' @param destfile The full local path the PDF should be written to, as
@@ -93,9 +82,8 @@ save_pdf = function(url, destfile, minimum_bytes = 2048) {
 
   if (file.exists(destfile)) { return("cached") }
 
-  ## otherwise the FEMA domain blocks our requests
   headers = c(
-    "User-Agent" = "Mozilla/5.0 (Linux; Android 11; SAMSUNG SM-G973U) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/14.2 Chrome/87.0.4280.141 Mobile Safari/537.36",
+    "User-Agent" = browser_user_agent(),
     "Accept" = "application/pdf",
     "Accept-Language" = "en-US",
     "Connection" = "keep-alive")
@@ -103,12 +91,8 @@ save_pdf = function(url, destfile, minimum_bytes = 2048) {
   ## Some listing links are percent-encoded twice: FEMA publishes
   ## "...Luise%25C3%25B1oIndians.pdf", where "%25" is an encoded "%", so the
   ## request asks for a file literally named "Luise%C3%B1o..." and returns 404.
-  ## The real filename contains "n" with a tilde, correctly encoded as "%C3%B1".
-  ## Undoing one layer of encoding recovers it. Tried only after the URL as
-  ## published fails, so a filename that genuinely contains a percent sign is
-  ## still fetched correctly on the first attempt.
+  ## Undoing one layer of encoding recovers it. 
   candidate_urls = unique(c(url, stringr::str_replace_all(url, "%25", "%")))
-
   downloaded = FALSE
   for (candidate_url in candidate_urls) {
     downloaded = tryCatch({
@@ -119,22 +103,19 @@ save_pdf = function(url, destfile, minimum_bytes = 2048) {
         mode = "wb")
       TRUE},
       error = function(e) FALSE,
-      warning = function(w) FALSE)
+      warning = function(w) NA)
 
-    if (downloaded) { break } }
+    if (isTRUE(downloaded)) { break } }
 
   is_pdf = FALSE
   if (file.exists(destfile) && file.size(destfile) >= minimum_bytes) {
     connection = file(destfile, "rb")
-    ## closed immediately rather than via on.exit(): the file.remove() below runs
-    ## before function exit, and Windows refuses to delete a file that still has
-    ## an open handle, which would leave the bad download in place
     file_header = tryCatch(
       rawToChar(readBin(connection, "raw", 4)),
       finally = close(connection))
     is_pdf = identical(file_header, "%PDF") }
 
-  if (!downloaded || !is_pdf) {
+  if (!is_pdf) {
     ## remove the partial or wrong-content file so this URL is retried next run
     if (file.exists(destfile)) { file.remove(destfile) }
     warning(
@@ -147,38 +128,23 @@ save_pdf = function(url, destfile, minimum_bytes = 2048) {
 
 #' @title Download Preliminary Damage Assessment (PDA) Reports to Disk
 #'
-#' @description Downloads every PDA report PDF that FEMA publishes into a local
+#' @description Downloads every PDA report that FEMA publishes into a local
 #'   directory, so that `get_preliminary_damage_assessments()` has a complete and
 #'   current set of source documents to parse. Run this before regenerating the
 #'   dataset; `get_preliminary_damage_assessments()` parses whatever is already on
 #'   disk and never fetches anything itself.
 #'
 #' @details Walks every page of FEMA's PDA report listing at
-#' https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports,
-#' advancing until a page returns no PDF links, and downloads any report not
-#' already present in `cache_directory`. Because the full listing is traversed on
-#' every run, the set of files on disk after a successful run is the complete set
-#' of reports FEMA publishes -- coverage does not depend on the caller working
-#' out which page numbers hold new reports.
+#' https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports
+#' and downloads any report not
+#' already present in `cache_directory`. 
 #'
 #' A page that errors is retried, and exhausting the retries raises an error
-#' rather than ending the walk. This matters because a transient failure and a
-#' genuinely empty final page are otherwise indistinguishable, and treating the
-#' former as the end of the listing would silently truncate the archive.
-#'
-#' The listing is server-rendered, so the PDF links are present in the HTML that
-#' `httr::GET()` returns and no headless browser is needed. An earlier version
-#' used `rvest::read_html_live()`, which requires `chromote`; that dependency is
-#' not declared by this package and is frequently absent, which made the
-#' function fail outright rather than merely run slowly.
-#'
-#' Note that FEMA's bot protection rejects requests that do not carry a
-#' browser-like `User-Agent`, and rejects them from some networks regardless, so
-#' a failure here is not necessarily a change to the listing.
+#' rather than ending the walk. 
 #'
 #' @param cache_directory The folder where scraped PDFs are written.
 #' @param max_pages A guard against an unbounded walk if the listing ever stops
-#'   returning empty pages. Raises an error if reached.
+#'   returning empty pages. 
 #' @param attempts_per_page How many times to try a listing page before treating
 #'   it as a failure.
 #' @param pages Which listing pages to read, as a numeric vector. The default
@@ -228,10 +194,8 @@ scrape_pda_pdfs = function(
   on.exit(options(timeout = original_timeout), add = TRUE)
   options(timeout = 200)
 
-  ## the same browser-like header the PDF downloads use; without it FEMA
-  ## returns 403 rather than the listing
   listing_headers = httr::add_headers(
-    "User-Agent" = "Mozilla/5.0 (Linux; Android 11; SAMSUNG SM-G973U) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/14.2 Chrome/87.0.4280.141 Mobile Safari/537.36",
+    "User-Agent" = browser_user_agent(),
     "Accept" = "text/html",
     "Accept-Language" = "en-US")
 
@@ -247,6 +211,7 @@ scrape_pda_pdfs = function(
   urls1 = character(0)
   page_number = if (walk_whole_listing) 0 else page_queue[1]
   page_index = 1
+  pages_read = 0
 
   repeat {
     page_urls = NULL
@@ -263,14 +228,10 @@ scrape_pda_pdfs = function(
           rvest::html_elements("a") %>%
           rvest::html_attr("href") %>%
           purrr::discard(~ is.na(.x)) %>%
-          ## anchored to the extension: an unanchored "pdf" match also picks up
-          ## links such as "/help-with-pdf-files", which are not reports
           purrr::keep(~ stringr::str_detect(.x, stringr::regex("\\.pdf$", ignore_case = TRUE)))},
         error = function(e) NULL)
 
       if (!is.null(page_urls)) { break }
-      ## exponential rather than linear: FEMA rate-limits a sustained walk and
-      ## the cooldown outlasts a few short pauses
       Sys.sleep(min(120, delay_seconds * 2 ^ attempt))
     }
 
@@ -285,17 +246,15 @@ scrape_pda_pdfs = function(
           "Reports from pages already read were not downloaded. To resume from ",
           "where this stopped, wait a few minutes and call:\n",
           "  scrape_pda_pdfs(pages = ", page_number, ":",
-          max(page_number + 49, page_number), ")\n",
+          page_number + 49, ")\n",
           "or raise delay_seconds / attempts_per_page for a slower, more ",
           "patient walk."),
         call. = FALSE) }
 
-    ## an empty page that loaded successfully is the end of the listing; only
-    ## meaningful when walking, since an explicit page list may legitimately
-    ## include a page beyond the end
     if (length(page_urls) == 0 && walk_whole_listing) { break }
 
     urls1 = c(urls1, page_urls)
+    pages_read = pages_read + 1
 
     if (walk_whole_listing) {
       page_number = page_number + 1
@@ -325,7 +284,7 @@ scrape_pda_pdfs = function(
   destinations = resolve_pdf_destinations(urls2)
 
   notify(
-    "Found ", nrow(destinations), " report(s) across ", page_number,
+    "Found ", nrow(destinations), " report(s) across ", pages_read,
     " listing page(s).")
 
   destinations2 = destinations %>%
@@ -349,11 +308,7 @@ scrape_pda_pdfs = function(
         "Do not treat the archive as complete until this count is zero."),
       call. = FALSE) }
 
-  ## Files present locally but no longer listed on the site. FEMA has not been
-  ## observed to withdraw a report (as of the 2026-07-30 archive, all 1,356
-  ## cached files were still listed), so this is a monitor rather than a known
-  ## problem: a withdrawn report would otherwise keep flowing into the dataset
-  ## with nothing to indicate it is no longer published.
+  ## Files present locally but not listed on the site. 
   orphans = setdiff(
     list.files(cache_directory, recursive = TRUE, pattern = "(?i)pdf$"),
     destinations2$destination_file)
@@ -370,58 +325,64 @@ scrape_pda_pdfs = function(
   invisible(destinations2)
 }
 
-#' Helper function to extract values from the PDAs
-#' @param text The inputted string of text
-#' @param term1 Where to begin matching
-#' @param term2 Where to finish matching
+#' Extract the value a report prints between two field labels
 #'
-#' @return All the text between term1 and term2, but not including either of the terms themselves
+#' @param text The report text to search.
+#' @param term1 The label the value follows.
+#' @param term2 The label the value runs up to.
+#'
+#' @return The text between `term1` and `term2`, excluding both terms.
 #' @noRd
 extract_value = function(text, term1, term2) {
 
-  ## Colons are optional. The reports render these fields as
-  ## "<label><footnote digit> <value>" with no colon anywhere -- verified across
-  ## all 1,356 cached reports, 2007-2025 -- but the patterns were written as if a
-  ## colon were present, so several of them matched nothing at all and their
-  ## columns were empty for every row. Making the colon optional matches the real
-  ## documents without having to know which labels ever carried one.
+  ## Colons are optional because most reports render these fields as
+  ## "<label><footnote digit> <value>" with no colon at all, while some print
+  ## one. 
   optional_colon = function(term) stringr::str_replace_all(term, ":", ":?")
 
+  ## Each term is wrapped in its own group before the two are joined, because
+  ## several call sites pass an alternation ("poverty households:|low income
+  ## households:").
   term1_grouped = stringr::str_c("(?:", optional_colon(term1), ")")
   term2_grouped = stringr::str_c("(?:", optional_colon(term2), ")")
 
-  ## Both terms are wrapped before being joined. Several call sites pass an
-  ## alternation (e.g. "poverty households:|low income households:"), and
-  ## unwrapped that composed to "A|B.*C" -- alternation binds loosest, so the
-  ## pattern matched a bare label with no value at all rather than either label
-  ## followed by a value.
-  ##
-  ## The span is matched lazily so the value ends at the FIRST occurrence of
-  ## term2; a greedy ".*" ran to the LAST occurrence, swallowing every
-  ## intervening field whenever a report repeated a label.
   stringr::str_extract(
     text,
     stringr::str_c(term1_grouped, ".*?", term2_grouped)) %>%
-    ## anchored, so a term that also occurs inside the value cannot be removed
-    ## from the middle of it
     stringr::str_remove(stringr::str_c("^", term1_grouped)) %>%
     stringr::str_remove(stringr::str_c(term2_grouped, "$")) %>%
-    stringr::str_squish() %>%
-    stringr::str_trim()
+    stringr::str_squish()
+}
+
+#' The dash characters the reports use interchangeably
+#'
+#' @return A length-one character regular expression character class.
+#' @noRd
+dash_class = function() { "[-\\u2010-\\u2015]" }
+
+#' Match a field label together with the dash that separates it from its value
+#'
+#' @param label The label text, without its separator.
+#' @return A regular expression matching the label and its separator.
+#' @noRd
+dash_label = function(label) {
+  stringr::str_c(label, "\\s*", dash_class(), "?\\s*")
+}
+
+#' Match a program's "Not requested" wording
+#'
+#' @param program The program name as the reports print it.
+#' @return A regular expression.
+#' @noRd
+not_requested_pattern = function(program) {
+  stringr::str_c(program, "\\s*", dash_class(), "?\\s*(N|n)ot\\s*(R|r)equested")
 }
 
 #' Drop a label's superscript footnote marker from an extracted value
 #'
 #' `pdftools` renders the superscript footnote numbers that FEMA attaches to
 #' several field labels inline with the text, so an extracted value arrives as
-#' "7 2.29" rather than "2.29". The marker is removed only when something
-#' follows it, so a field whose value genuinely is a small integer -- "Major
-#' Damage - 1" -- keeps that value rather than having it stripped as a marker.
-#'
-#' This runs after extraction rather than inside `extract_value()` because a
-#' leading digit is only identifiable as a footnote once the full value span is
-#' in hand: consuming an optional digit during matching would eat the real value
-#' in the single-integer case.
+#' "7 2.29" rather than "2.29". 
 #'
 #' @param value A character vector of extracted values.
 #' @return `value` with a leading footnote marker removed where present.
@@ -433,27 +394,31 @@ remove_footnote_marker = function(value) {
     value)
 }
 
+#' Take the first whitespace-separated token of an extracted value
+#'
+#' An extracted span often carries the beginning of the next field after the
+#' value itself, so the value is the first token. Used wherever a single figure
+#' is wanted from a span, so that all of them are taken the same way.
+#'
+#' @param value A character vector of extracted values.
+#' @return A character vector of first tokens.
+#' @noRd
+first_token = function(value) {
+  stringr::str_split(value, " ") %>% purrr::map_chr(~ .x[1])
+}
+
 #' Version of the PDA parsing logic
 #'
 #' Written into every generated dataset as `parser_version` and checked when a
 #' cached dataset is read. Increment it whenever a change alters the values this
 #' code produces.
 #'
-#' This exists because the shipped cache was found to have been written by a
-#' version of this code that no longer exists in the repository: it held
-#' comma-free titles and a fully populated `event_date_determined` that the
-#' committed parser could not reproduce, and reading the cache concealed that for
-#' as long as nobody regenerated the data. A dataset that cannot be traced to the
-#' code that made it cannot be relied on for publication.
-#'
 #' @return A length-one character version string.
 #' @noRd
-pda_parser_version = function() { "2.1.0" }
+pda_parser_version = function() { "2.7.0" }
 
 #' Warn when a cached dataset was written by different parsing logic
 #'
-#' Reads only the header row, so this costs nothing on a large cache.
-#'
 #' @param file_path Path to the cached CSV.
 #' @return Invisibly `TRUE` if the versions match, `FALSE` otherwise.
 #' @noRd
@@ -481,10 +446,8 @@ check_cache_parser_version = function(file_path) {
 #' Set impossible percentage values to NA
 #'
 #' Columns named `*_percent` record shares of a population and cannot fall
-#' outside 0-100. A handful of reports yield values far outside that range
-#' (79,186 and 12,778 were observed), which means the extracted text was not the
-#' intended figure. These are set to `NA` rather than published, and the count is
-#' reported so the loss is visible rather than silent.
+#' outside 0-100. A handful of reports yield values far outside that range; 
+#' These are set to `NA` rather than published, and the number of such occurrences is reported.
 #'
 #' @param pda_df A dataframe of extracted PDA records.
 #' @return `pda_df` with out-of-range percentages replaced by `NA`.
@@ -497,16 +460,6 @@ drop_impossible_percentages = function(pda_df) {
 
   if (length(percent_columns) == 0) { return(pda_df) }
 
-  n_dropped = percent_columns %>%
-    purrr::map_dbl(~ sum(pda_df[[.x]] < 0 | pda_df[[.x]] > 100, na.rm = TRUE)) %>%
-    sum()
-
-  if (n_dropped > 0) {
-    message(
-      stringr::str_c(
-        n_dropped, " percentage value(s) fell outside 0-100 and were set to NA; ",
-        "the text extracted for those fields was not the intended figure.")) }
-
   pda_df %>%
     dplyr::mutate(
       dplyr::across(
@@ -517,11 +470,7 @@ drop_impossible_percentages = function(pda_df) {
 #' Columns that are not parsed field values
 #'
 #' Identity and metadata columns, exempt from the whitespace, punctuation, and
-#' numeric-coercion steps that every extracted value passes through. Defined once
-#' rather than repeated at each cleanup step: the list was previously written out
-#' three times, and a column missing from any one of them was silently coerced --
-#' stripping ":" from `path` corrupted Windows drive letters, and adding
-#' `disaster_number_filename` without updating all three turned it into a double.
+#' numeric-coercion steps.
 #'
 #' @return A character vector of column names.
 #' @noRd
@@ -552,39 +501,18 @@ extract_pda_attributes = function(path) {
     stringr::str_c(collapse = " ") %>%
     stringr::str_replace_all("\\\n", " ")
 
-  ## Outcome is read from FEMA's own filename convention first
-  ## ("PDAReport_AppealDenial-KY.pdf", "PDAReport_Denial-GA.pdf", and otherwise
-  ## an approval), falling back to the report title. The previous rule scanned
-  ## the entire document body and reclassified any report containing the word
-  ## "denial" or "denied" anywhere -- including in boilerplate describing the
-  ## appeals process -- as an approved appeal. It also keyed on the literal
-  ## "Denial Denied", which is an artefact of two title fields running together
-  ## rather than a phrase FEMA writes deliberately.
-  ##
-  ## Only the title is consulted in the fallback, never the whole body, so
-  ## process boilerplate cannot change the classification.
   filename_lower = tolower(basename(path))
 
-  ## Both specific tests run before either general one. A report can be filed
-  ## under a generic "Denial" filename while its title states "Denial of Appeal",
-  ## and checking the filename's general case first misclassified 24 appeal
-  ## denials as first-instance denials.
-  ## An approved appeal is identified from the report body, not the title: these
-  ## reports are titled and named exactly like first-instance approvals (e.g.
-  ## PDAReport_FEMA4583DR-MD.pdf) and carry a disaster number, because the appeal
-  ## succeeded. The signal is the word "appealed", which across all 1,356 reports
-  ## occurs in 115 of them and always within a narrative of an actual appeal
-  ## ("Governor Hogan appealed the denial"); 114 of those use the exact phrase
-  ## "appealed the denial". No report contains "appeal" without "appealed", so
-  ## there is no appeals-process boilerplate for this to misfire on.
-  ##
-  ## Matching on "denied" or "denial" instead, as an earlier version did, is what
-  ## caused misclassification: those words appear in genuine first-instance
-  ## approvals for unrelated reasons, such as a partial denial that the governor
-  ## then amended rather than appealed (pda_report_fema_dr_4099_pa.pdf).
-  ##
-  ## The denial classes are settled first, so a report that was itself denied on
-  ## appeal cannot reach this branch.
+  ## The outcome is read from FEMA's filename convention
+  ## ("PDAReport_AppealDenial-KY.pdf", "PDAReport_Denial-GA.pdf", otherwise an
+  ## approval), falling back to the report title. 
+
+  ## An approved appeal is the exception: it is identified from the report body,
+  ## because such a report is titled and named exactly like a first-instance
+  ## approval and carries a disaster number. The
+  ## signal is the word "appealed", which occurs only within a narrative of an
+  ## actual appeal ("Governor Hogan appealed the denial") and never as
+  ## boilerplate. 
   event_type = dplyr::case_when(
     stringr::str_detect(filename_lower, "appeal[-_ ]?denial")              ~ "appeal_denial",
     stringr::str_detect(text_event_name, "Denial of Appeal|Appeal Denied") ~ "appeal_denial",
@@ -593,70 +521,50 @@ extract_pda_attributes = function(path) {
     stringr::str_detect(text1, stringr::regex("appealed", ignore_case = TRUE)) ~ "appeal_approved",
     TRUE                                                                   ~ "approved")
 
-  ## A report using the tribal layout names its per-capita figures without a
-  ## "Statewide"/"Territory" qualifier. This is derived from the document rather
-  ## than from title keywords alone, because keyword matching missed 59 reports
-  ## that use the tribal wording, and the flag gates a re-extraction branch that
-  ## silently changes several Public Assistance values when it is wrong.
-  uses_tribal_layout =
-    stringr::str_detect(text1, "Per capita impact") &
-    !stringr::str_detect(text1, "(Statewide|Territory|Commonwealth|District) per capita impact")
-
-  text_pda_preempted = ""
-
-  if (event_type %in% c("approved", "appeal_approved")) {
-    ## the event was so severe that no pda was conducted
-    if (stringr::str_detect(text1, "requirement for a joint PDA may be waived")) {
-      text_pda_preempted = "requirement for a joint PDA may be waived" }
+  ## A report using the tribal layout names its per capita figures without a
+  ## "Statewide"/"Territory" qualifier. Deriving this from the document rather
+  ## than from title keywords alone catches the reports that use the tribal
+  ## wording without saying so in their title.
 
-    ## the main attributes are stored here
-    text_primary = text1 %>%
-      stringr::str_extract("Summary of Damage Assessment.*") %>%
-      stringr::str_remove("The Preliminary Damage Assessment PDA process is a mechanism.*|The preliminary damage assessment PDA process.*") %>%
-      stringr::str_squish() %>%
-      stringr::str_remove_all("\\uf0b7") %>%
-      stringr::str_replace_all("(\\:[0-9]|\\: [0-9] )", ":") }
-
-  if (event_type %in% c("denial", "appeal_denial")) {
-    ## the main attributes are stored here
-    text_primary = text1 %>%
-      stringr::str_extract("Summary of Damage Assessment.*") %>%
-      stringr::str_remove("The (P|p)reliminary (D|d)amage (A|a)ssessment PDA process is a mechanism.*|The preliminary damage assessment PDA process.*") %>%
-      stringr::str_squish() %>%
-      stringr::str_remove_all("\\uf0b7") %>%
-      stringr::str_replace_all("(\\:[0-9]|\\: [0-9] )", ":") }
+  uses_tribal_layout =
+    stringr::str_detect(text1, stringr::regex("per capita impact", ignore_case = TRUE)) &
+    !stringr::str_detect(
+      text1, "(Statewide|Territory|Commonwealth|District) per capita impact")
+
+  is_denial = event_type %in% c("denial", "appeal_denial")
+
+  ## an event so severe that no joint PDA was conducted; recorded in the text so
+  ## that `pa_preemptive_declaration` can read it back below
+  text_pda_preempted = dplyr::if_else(
+    !is_denial & stringr::str_detect(text1, "requirement for a joint PDA may be waived"),
+    "requirement for a joint PDA may be waived",
+    "")
+
+  ## The summary section holds the field values--we drop the boilerplate.
+  boilerplate_pattern = dplyr::if_else(
+    is_denial,
+    "The (P|p)reliminary (D|d)amage (A|a)ssessment PDA process is a mechanism.*|The preliminary damage assessment PDA process.*",
+    "The Preliminary Damage Assessment PDA process is a mechanism.*|The preliminary damage assessment PDA process.*")
+
+  text_primary = text1 %>%
+    stringr::str_extract("Summary of Damage Assessment.*") %>%
+    stringr::str_remove(boilerplate_pattern) %>%
+    stringr::str_squish() %>%
+    stringr::str_remove_all("\\uf0b7") %>%
+    stringr::str_replace_all("(\\:[0-9]|\\: [0-9] )", ":")
 
   text = stringr::str_c(text_event_name, text_pda_preempted, text_primary, sep = " ")
 
-  ## the disaster number is parsed from the PDF text (the FEMA-XXXX-DR pattern) as the
-  ## primary strategy; filename parsing is only a fallback when that pattern is absent,
-  ## since some filenames contain unrelated 4-digit sequences (e.g. embedded dates) that
-  ## collide with real disaster numbers from other files
-  ## Separators around the number vary across report vintages ("FEMA-4857-DR",
-  ## "FEMA 4857 DR", "FEMA4857DR"), so they are matched permissively rather than
-  ## requiring hyphens.
-  disaster_number_from_text = text0 %>%
-    stringr::str_extract(stringr::regex("FEMA[-_ ]?([0-9]{4})[-_ ]?DR", ignore_case = TRUE)) %>%
-    stringr::str_extract("[0-9]{4}")
-
-  ## Filename fallback, used only when the report body states no disaster number.
-  ##
-  ## The number must be anchored to a literal "FEMA...DR" in the *basename*. The
-  ## previous fallback took the first four consecutive digits anywhere in the
-  ## full path, which fabricated numbers two ways. Dates embedded in filenames
-  ## became disaster numbers -- "PDAReportAppealDenial-PA_090903.pdf" yielded
-  ## 0909 and "PDAReportDenialNJ_2019.pdf" yielded 2019, which is itself a real
-  ## disaster number -- affecting 13 reports, all of them denials, which FEMA
-  ## never assigns a number to at all. And because it scanned the whole path
-  ## rather than the filename, any four-digit run in a parent directory would
-  ## have been picked up for every report beneath it.
-  ##
-  ## Where neither the text nor the filename names a disaster, the value stays
-  ## NA. That is the correct answer for a denied request: no declaration was
-  ## made, so no number exists to record.
-  disaster_number_from_filename = basename(path) %>%
-    stringr::str_extract(stringr::regex("FEMA[-_ ]?([0-9]{4})[-_ ]?DR", ignore_case = TRUE)) %>%
-    stringr::str_extract("[0-9]{4}")
+  ## The disaster number is read from the report body first and from the
+  ## filename only where the body states none.
+  read_disaster_number = function(x) {
+    x %>%
+      stringr::str_extract(
+        stringr::regex("FEMA[-_ ]?([0-9]{4})[-_ ]?DR", ignore_case = TRUE)) %>%
+      stringr::str_extract("[0-9]{4}") }
+
+  disaster_number_from_text = read_disaster_number(text0)
+  disaster_number_from_filename = read_disaster_number(basename(path))
 
   result = tibble::tibble(
       path = path,
@@ -669,128 +577,123 @@ extract_pda_attributes = function(path) {
       disaster_number_filename = disaster_number_from_filename,
       event_type = event_type,
       event_title = text_event_name,
-      ## Word-bounded so "Nation" no longer matches "National", and combined
-      ## with the layout test above rather than relying on title keywords alone.
-      ## "Cooperative" and the hardcoded disaster number 4844 are dropped: the
-      ## former is not tribal-specific and the latter was a patch for a single
-      ## report that the layout test now covers.
+      ## Keywords in the title, combined with the layout test above rather than
+      ## relied on alone. The keywords are word-bounded so that, for example,
+      ## "Nation" does not match "National".
+      ##
+      ## "Village", "Traditional Council" and "IRA Council" are included because
+      ## an Alaska Native village may name itself with none of the other words --
+      ## "Newtok Village" carries none -- and a request from one that also
+      ## reports in the state layout would otherwise be read as a state's.
       event_native_flag = dplyr::if_else(
         stringr::str_detect(
           event_title,
           stringr::regex(
-            "\\b(Native|Tribe|Tribes|Tribal|Indians|Nation|Band|Pueblo|Rancheria|Reservation)\\b",
+            stringr::str_c(
+              "\\b(Native|Tribe|Tribes|Tribal|Indians|Nation|Band|Pueblo|",
+              "Rancheria|Reservation|Villages?)\\b|",
+              "\\b(Traditional|IRA) Council\\b"),
             ignore_case = TRUE)) |
           uses_tribal_layout,
         1, 0),
-      ## The dash between the program name and "Not requested" varies across
-      ## reports: 222 use an en-dash and 451 a plain hyphen. Matching only the
-      ## en-dash, as this did, left those 451 reports flagged as having requested
-      ## Individual Assistance when they state the opposite -- a third of the
-      ## dataset. Because the flag defaults to 1, every unmatched wording
-      ## silently becomes "requested", so the pattern accepts any dash character
-      ## (or none) and any surrounding whitespace.
       ia_requested = dplyr::if_else(
-        stringr::str_detect(
-          text,
-          "Individual Assistance\\s*[-\\u2010-\\u2015]?\\s*(N|n)ot\\s*(R|r)equested"),
+        stringr::str_detect(text, not_requested_pattern("Individual Assistance")),
         0, 1),
-      ia_residences_impacted = text %>% extract_value(term1 = "Residences Impacted:", term2 = "Destroyed -"),
-      ia_residences_destroyed = text %>% extract_value(term1 = "Destroyed -", term2 = "Major Damage -"),
-      ia_residences_major_damage = text %>% extract_value(term1 = "Major Damage -", term2 = "Minor Damage -"),
-      ia_residences_minor_damage = text %>% extract_value(term1 = "Minor Damage -", term2 = "Affected -"),
-      ia_residences_affected = text %>% extract_value(term1 = "Affected -", term2 = "Percentage of insured residences:"),
-      ## term2 lists the labels actually observed to follow this one across the
-      ## 1,356 cached reports, most frequent first: low income (799), poverty
-      ## (436), Flood (99), elderly (13). It previously named only "Flood", which
-      ## follows in 99 reports, so 450 of the 472 reports carrying a real value
-      ## here extracted nothing.
+      ia_residences_impacted = text %>% extract_value(term1 = "Residences Impacted:", term2 = dash_label("Destroyed")),
+      ia_residences_destroyed = text %>% extract_value(term1 = dash_label("Destroyed"), term2 = dash_label("Major Damage")),
+      ia_residences_major_damage = text %>% extract_value(term1 = dash_label("Major Damage"), term2 = dash_label("Minor Damage")),
+      ia_residences_minor_damage = text %>% extract_value(term1 = dash_label("Minor Damage"), term2 = dash_label("Affected")),
+      ia_residences_affected = text %>% extract_value(term1 = dash_label("Affected"), term2 = "Percentage of insured residences:"),
       ia_residences_insured_total_percent = text %>% extract_value(
         term1 = "Percentage of insured residences:",
         term2 = "Percentage of low income households|Percentage of poverty households|Percentage of elderly households|Flood"),
-      ia_residences_insured_flood_percent = text %>% stringr::str_extract("[0-9]{1,2}\\.[0-9]\\%( Flood|Flood)") %>% stringr::str_remove("Flood") %>% stringr::str_squish(),
+      ia_residences_insured_flood_percent = text %>%
+        stringr::str_extract("[0-9]{1,3}(\\.[0-9]{1,2})?\\s*\\%\\s*Flood") %>%
+        stringr::str_remove("Flood") %>%
+        stringr::str_remove("\\%") %>%
+        stringr::str_squish(),
       ia_households_poverty_percent = text %>% extract_value(term1 = "Percentage of poverty households:|Percentage of low income households:", term2 = "Percentage of ownership households:|Percentage of elderly households:"),
-      ## observed successors: Pre-Disaster Unemployment (521), Total Individual
-      ## Assistance cost estimate (152), Disability (4). The single successor
-      ## named previously ("Population receiving...") in practice follows this
-      ## label rarely, leaving 185 of the 259 real values unextracted.
       ia_households_owner_percent = text %>% extract_value(
         term1 = "Percentage of ownership households:",
         term2 = "Population receiving other government|Pre-Disaster Unemployment|Total Individual Assistance cost estimate|Disability:"),
-      ## the label wraps across a line in the source, so the words between
-      ## "government" and "SNAP" may be separated by arbitrary whitespace
       ia_population_other_government_assistance_percent = text %>% extract_value(
         term1 = "Population receiving other government\\s+assistance such as SSI and SNAP:",
         term2 = "Pre-Disaster Unemployment|Age 65 and older:|Total Individual Assistance cost estimate"),
       ia_pre_disaster_unemployment_percent = text %>% extract_value(term1 = "Pre-Disaster Unemployment", term2 = "Age 65 and older:"),
       ia_65plus_percent = text %>% extract_value(term1 = "Age 65 and older:", term2 = "Age 18 and under:"),
       ia_18below_percent = text %>% extract_value(term1 = "Age 18 and under:", term2 = "Disability:"),
-      ## the parentheses in "(ICC)" are removed from `text1` upstream, so a
-      ## pattern requiring them could never match and this column was empty for
-      ## every one of the 1,356 cached reports
       ia_disability_percent = text %>% extract_value(term1 = "Disability:", term2 = "IHP Cost to Capacity ICC Ratio"),
       ia_ihp_cost_to_capacity_ratio = text %>% extract_value(term1 = "IHP Cost to Capacity ICC Ratio:", term2 = "Total Individual Assistance cost estimate"),
       ia_cost_estimate_total = text %>% extract_value(term1 = "Total Individual Assistance cost estimate", term2 = "Primary Impact"),
-      ## same dash-agnostic form as ia_requested above, so the two flags are
-      ## derived identically rather than by two differently-permissive patterns
       pa_requested = dplyr::if_else(
-        stringr::str_detect(
-          text,
-          "Public Assistance\\s*[-\\u2010-\\u2015]?\\s*(N|n)ot\\s*(R|r)equested"),
+        stringr::str_detect(text, not_requested_pattern("Public Assistance")),
         0, 1),
       pa_preemptive_declaration = dplyr::if_else(stringr::str_detect(text, "requirement for a joint PDA may be waived"), 1, 0),
       pa_primary_impact = text %>% extract_value(term1 = "Primary Impact", term2 = "Total Public Assistance cost estimate:"),
       ## Tribal reports label this "Per capita impact:" rather than "Statewide
-      ## per capita impact:". A tribal branch further down re-extracts these, but
-      ## it only fires on event_native_flag, which is keyword-matched from the
-      ## report title and misses 59 reports that use the tribal wording. Adding
-      ## the bare form here makes extraction independent of that flag. The
-      ## capitalised "Per" cannot match inside "Statewide per capita impact:",
-      ## so state reports are unaffected.
+      ## per capita impact:".
       pa_cost_estimate_total = text %>% extract_value(
         term1 = "Total Public Assistance cost estimate:",
-        term2 = "(Statewide|Territory|Commonwealth|District) per capita impact:|Per capita impact:"),
+        term2 = "(Statewide|Territory|Commonwealth|District) per capita impact:|[Pp]er capita impact:"),
       pa_per_capita_impact_statewide = text %>% extract_value(term1 = "(Statewide|Territory|Commonwealth) per capita impact", term2 = "(Statewide|Territory|Commonwealth|District) per capita impact indicator"),
       pa_per_capita_impact_indicator_statewide = text %>% extract_value(term1 = "(Statewide|Territory|Commonwealth) per capita impact indicator", term2 = "(Countywide per capita impact|\\$[0-9]{1}\\.[0-9]{1,2} [0-9]{1})"),
       pa_per_capita_impact_countywide = text %>% extract_value(term1 = "Countywide per capita impact", term2 = "Countywide per capita impact indicator"),
-      pa_per_capita_impact_indicator_countywide = text %>% extract_value(term1 = "Countywide per capita impact indicator:", term2 = "$"),
+      pa_per_capita_impact_indicator_countywide = text %>%
+        extract_value(
+          term1 = "Countywide per capita impact indicator:",
+          term2 = "The [Pp]reliminary [Dd]amage|Footnote|$"),
       text = text1) %>%
     dplyr::mutate(
-      ## Runs first, before any field-specific cleanup: several of the steps
-      ## below take the first whitespace-separated token as the value, which is
-      ## the footnote marker rather than the number whenever one is present.
       dplyr::across(
-        .cols = dplyr::where(is.character) & -c(path, disaster_number, event_type, event_title, text),
+        .cols = dplyr::where(is.character) & -dplyr::any_of(non_extracted_columns()),
         .fns = remove_footnote_marker),
-      ## the previous "take everything up to the last space" step is gone: it
-      ## existed to trim the oversized span the old term2 ("Flood") produced, and
-      ## against a correctly-delimited value such as "42%" it matches nothing and
-      ## returns NA
       ia_cost_estimate_total = stringr::str_remove(ia_cost_estimate_total, "Public Assistance"),
-      pa_per_capita_impact_indicator_statewide = stringr::str_split(pa_per_capita_impact_indicator_statewide, " ") %>% purrr::map_chr(~ .[1]),
-      ## in the case of Samoa, this is the last value
+      pa_per_capita_impact_indicator_statewide = first_token(pa_per_capita_impact_indicator_statewide),
+      ## in the case of American Samoa, this is the last value
       pa_per_capita_impact_indicator_statewide = dplyr::if_else(
         nchar(pa_per_capita_impact_indicator_statewide) < 3,
-        text %>% extract_value(term1 = "Statewide per capita impact indicator", term2 = "$") %>% stringr::str_split(" ") %>% purrr::map_chr(~ .[1]),
+        text %>%
+          extract_value(term1 = "Statewide per capita impact indicator", term2 = "$") %>%
+          first_token(),
         pa_per_capita_impact_indicator_statewide),
-      ## the first number in the span, rather than a blind five-character cut:
-      ## the truncation happened to suit values of the form "N.NN" and silently
-      ## corrupted anything longer or shorter
-      pa_per_capita_impact_indicator_countywide = stringr::str_extract(
-        pa_per_capita_impact_indicator_countywide, "[0-9]+\\.?[0-9]*"),
-      ## scoped away from path/disaster_number/event_type/event_title/text (which should
-      ## not have %, :, $, or , stripped -- doing so on `path` corrupted the colon in
-      ## Windows drive letters, e.g. "C:/...")
+      pa_per_capita_impact_indicator_countywide = pa_per_capita_impact_indicator_countywide %>%
+        stringr::str_remove("\\s+[0-9]{1,2}\\s*$") %>%
+        stringr::str_trim(),
+      pa_per_capita_impact_indicator_countywide = dplyr::if_else(
+        stringr::str_detect(
+          pa_per_capita_impact_indicator_countywide,
+          stringr::str_c("^", dash_class())),
+        NA_character_,
+        stringr::str_extract(
+          pa_per_capita_impact_indicator_countywide, "[0-9]+\\.?[0-9]*")),
       dplyr::across(
         .cols = -dplyr::all_of(non_extracted_columns()),
-        .fns = ~ stringr::str_remove_all(.x, "\\%|\\:|\\$|\\,") %>% stringr::str_trim() %>% stringr::str_squish()))
+        .fns = ~ stringr::str_remove_all(.x, "\\%|\\:|\\$|\\,") %>% stringr::str_squish()))
 
-  ## tribes have differently structured PDA report fields
+  ## Tribes have differently structured PDA report fields: the per capita labels
+  ## carry no "Statewide" qualifier, so the patterns above match nothing and the
+  ## three fields are re-read here.
+  ##
+  ## These read the local `text` -- the report title and its summary section --
+  ## rather than the `text` column.
   if (result$event_native_flag == 1) {
+    tribal_cost_estimate = extract_value(
+      text,
+      term1 = "Total Public Assistance cost estimate:",
+      term2 = "[Pp]er capita impact:")
+    tribal_impact = extract_value(
+      text,
+      term1 = "[Pp]er capita impact:",
+      term2 = "[Pp]er capita impact indicator:")
+    tribal_indicator = extract_value(
+      text,
+      term1 = "[Pp]er capita impact indicator:",
+      term2 = "Countywide per capita impact|The [Pp]reliminary|$")
     result = result %>%
       dplyr::mutate(
-        pa_cost_estimate_total = text %>% extract_value(term1 = "Total Public Assistance cost estimate", term2 = "Per capita impact"),
-        pa_per_capita_impact_statewide = text %>% extract_value(term1 = "Per capita impact", term2 = "Per capita impact indicator"),
-        pa_per_capita_impact_indicator_statewide = text %>% extract_value(term1 = "Per capita impact indicator", term2 = "$") %>% stringr::str_remove("^8 ")) }
+        pa_cost_estimate_total = remove_footnote_marker(tribal_cost_estimate),
+        pa_per_capita_impact_statewide = remove_footnote_marker(tribal_impact),
+        pa_per_capita_impact_indicator_statewide = remove_footnote_marker(tribal_indicator)) }
 
   months = c(
     "January", "February", "March", "April", "May", "June", "July", "August",
@@ -798,62 +701,45 @@ extract_pda_attributes = function(path) {
     stringr::str_c(collapse = "|")
   date_match_string = stringr::str_c("Denied (on |)(", months, ") [0-9]{1,2},? [0-9]{4}")
   first_date_match_string = stringr::str_c("(", months, ") [0-9]{1,2},? [0-9]{4}")
-  ## columns that should not have their raw values reformatted/stripped by the
-  ## cleanup steps below (e.g. stripping ":" from `path` corrupted Windows drive
-  ## letters like "C:/...", and 0/1,356 cached rows then failed to match a file on disk)
+
+  ## A value beginning with FEMA's dash placeholder is a field the report left
+  ## blank, and the whole value is discarded rather than having the dash
+  ## stripped off the front. Discarding the whole
+  ## value is safe because no real value ever follows the placeholder: every
+  ## dash-led value is either empty or a one- or two-digit
+  ## footnote marker.
+  clean_extracted_value = function(value) {
+    value1 = stringr::str_squish(value)
+    value2 = dplyr::if_else(
+      stringr::str_detect(value1, stringr::str_c("^", dash_class(), "(\\s|$)")),
+      NA_character_,
+      value1)
+    value3 = stringr::str_remove_all(value2, "\\$|\\:|\\,")
+    dplyr::if_else(stringr::str_detect(value3, "^N.A$"), NA_character_, value3) }
+
+  summarise_countywide = function(matches, summary_function) {
+    purrr::map_dbl(
+      matches,
+      ~ if (length(.x) == 0 || all(is.na(.x))) {
+          NA_real_
+        } else {
+          summary_function(as.numeric(.x), na.rm = TRUE) }) }
 
   result2 = result %>%
     dplyr::mutate(
-      dplyr::across(-dplyr::all_of(non_extracted_columns()), ~ stringr::str_squish(.x) %>% stringr::str_trim()),
-      ## A value that begins with FEMA's dash placeholder is a field the report
-      ## left blank, and the whole value is discarded rather than having the
-      ## dash stripped off the front.
-      ##
-      ## Stripping it, as this previously did, did not leave an empty value. FEMA
-      ## prints an unreported field as a dash and sets the *next* label's
-      ## superscript footnote number beside it, which `pdftools` renders inline:
-      ## "Age 65 and older: -   0   Age 18 and under:". Removing the dash left
-      ## the footnote number, which the numeric coercion below then took as the
-      ## measurement. That put 258 impossible zeros into the demographic share
-      ## columns -- a 0% pre-disaster unemployment rate, no residents over 65 --
-      ## and turned eight cost estimates into $2. Because a blank field is
-      ## indistinguishable from a real one once the dash is gone, the error was
-      ## invisible in the finished dataset.
-      ##
-      ## Discarding the whole value is safe because no real value ever follows
-      ## the placeholder: across all 1,381 cached reports and every extracted
-      ## field, 5,358 values begin with a dash and not one of them contains a
-      ## decimal or a number of three or more digits. Each is either empty or a
-      ## one- or two-digit footnote marker.
-      ##
-      ## Any dash character is accepted, matching how `ia_requested` and
-      ## `pa_requested` are derived, because the reports use an en-dash and a
-      ## plain hyphen interchangeably.
-      dplyr::across(
-        -dplyr::all_of(non_extracted_columns()),
-        ~ dplyr::if_else(
-          stringr::str_detect(.x, "^[-\\u2010-\\u2015](\\s|$)"), NA_character_, .x)),
-      dplyr::across(-dplyr::all_of(non_extracted_columns()), ~ stringr::str_remove_all(.x, "\\$|\\:|\\,")),
-      dplyr::across(-dplyr::all_of(non_extracted_columns()), ~ dplyr::if_else(stringr::str_detect(.x, "^N.A$"), NA_character_, .x)),
+      dplyr::across(-dplyr::all_of(non_extracted_columns()), clean_extracted_value),
       pa_per_capita_impact_countywide_1 = pa_per_capita_impact_countywide %>%
         stringr::str_extract_all("[0-9]{1,4}\\.[0-9]{1,3}"),
-      ## guard on length==0 or all-NA rather than is.na(.x): pa_per_capita_impact_countywide_1
-      ## is a list-column from str_extract_all(), where a no-match row is character(0) (not
-      ## NA -- is.na() on that list silently returns FALSE) and an NA *input* row is a
-      ## length-1 NA_character_ (not character(0)); either previously slipped through to
-      ## max()/min() on an effectively-empty vector, producing -Inf/Inf instead of NA
-      pa_per_capita_impact_countywide_max = pa_per_capita_impact_countywide_1 %>%
-        purrr::map_dbl(~ if (length(.x) == 0 || all(is.na(.x))) { NA_real_ } else { .x %>% as.numeric() %>% max(na.rm = TRUE) }),
-      pa_per_capita_impact_countywide_min = pa_per_capita_impact_countywide_1 %>%
-        purrr::map_dbl(~ if (length(.x) == 0 || all(is.na(.x))) { NA_real_ } else { .x %>% stringr::str_remove_all("\\(|\\)") %>% as.numeric() %>% min(na.rm = TRUE) }),
+      pa_per_capita_impact_countywide_max =
+        summarise_countywide(pa_per_capita_impact_countywide_1, max),
+      pa_per_capita_impact_countywide_min =
+        summarise_countywide(pa_per_capita_impact_countywide_1, min),
       ## The determination date is taken from the report title where it states
       ## one, then from an explicit "Denied on <date>" statement, and finally
       ## from the first date printed in the document. That last source carries
-      ## most of the coverage: 792 of 1,356 reports name no month anywhere in
-      ## their title, and for those the date at the head of the document is the
-      ## determination date (verified against the cached dataset, which this
-      ## reproduces). Without it this column is NA for well over half the rows,
-      ## and any analysis filtering on the date silently loses them.
+      ## most of the coverage: well over half of reports name no month anywhere
+      ## in their title, and for those the date at the head of the document is
+      ## the determination date.
       event_date_determined = event_title %>% date_string_to_date,
       event_date_determined = dplyr::if_else(
         is.na(event_date_determined),
@@ -867,43 +753,30 @@ extract_pda_attributes = function(path) {
         .cols = -dplyr::all_of(c(
           non_extracted_columns(),
           "event_date_determined", "pa_per_capita_impact_countywide", "pa_primary_impact")),
-        .fns = ~ stringr::str_split(.x, " ") %>% purrr::map_chr(~ .[1]) %>% as.numeric)) %>%
+        .fns = ~ first_token(.x) %>% as.numeric)) %>%
     dplyr::select(-pa_per_capita_impact_countywide_1) %>%
     dplyr::select(disaster_number, dplyr::matches("^event"), dplyr::matches("^pa"), dplyr::everything())
 
   return(result2)
 }
 
-#' Columns holding a dollar total, and the smallest total that is believable
+#' Columns holding a dollar total, and a floor that is greater than possible footnote numbering
 #'
-#' FEMA prints a superscript footnote marker next to several field labels, and
-#' `pdftools` renders it inline with the value, so a mis-parsed total arrives as
-#' the marker itself -- a number between 1 and 20 -- rather than as a cost. No
-#' genuine statewide or tribal cost estimate is that small: the smallest
-#' non-zero total in the 2026-07-30 archive is roughly 250,000 dollars. A floor
-#' of 1,000 therefore separates a footnote marker from a real total with a wide
-#' margin on both sides. Exact zeros are left alone, because a report can
-#' legitimately state a zero cost for a program it did not request.
+#' This catches potential footmarks that have been initially captured as meaningful field values
 #'
 #' @return A named list with `columns` and `floor`.
 #' @noRd
 pda_dollar_columns = function() {
   list(
     columns = c("pa_cost_estimate_total", "ia_cost_estimate_total"),
-    floor = 1000)
+    floor = 50)
 }
 
 #' Plausible ranges for FEMA's statutory per capita thresholds
 #'
 #' These two fields are not estimates but published statutory dollar
 #' thresholds, so their values are known in advance and a value outside the
-#' range is a mis-extraction rather than an unusual disaster. The statewide
-#' threshold has run from 1.24 to 1.94 dollars and the countywide from 3.11 to
-#' 4.60 across the whole archive; the ranges below are widened slightly to
-#' allow for future indexation. The two are close enough in form that one
-#' field's value is readily extracted into the other's column -- a statewide
-#' indicator of 3.11 is the countywide threshold in the wrong place -- and the
-#' non-overlapping ranges are what make that detectable.
+#' range is a mis-extraction rather than an unusual disaster.
 #'
 #' @return A named list of two-element numeric vectors.
 #' @noRd
@@ -913,6 +786,160 @@ pda_indicator_ranges = function() {
     pa_per_capita_impact_indicator_countywide = c(3.00, 5.00))
 }
 
+#' Columns holding a measured value rather than a flag or an identifier
+#'
+#' Counts, dollars, percentages, and ratios. The 0/1 flags and the identity
+#' columns are excluded because neither the quality checks nor the requested-flag
+#' tie-break describe them.
+#'
+#' @param pda_df A dataframe of extracted PDA records.
+#' @return A character vector of column names.
+#' @noRd
+program_measure_columns = function(pda_df) {
+  flag_columns = c(
+    "event_native_flag", "ia_requested", "pa_requested",
+    "pa_preemptive_declaration")
+
+  names(pda_df) %>%
+    purrr::discard(~ .x %in% c(non_extracted_columns(), flag_columns, "parser_version")) %>%
+    purrr::keep(~ is.numeric(pda_df[[.x]]))
+}
+
+#' Whether a report states any measurement for one assistance program
+#'
+#' Used both to settle a report that contradicts itself and to check for values
+#' recorded against a program the report says was not requested, so that the two
+#' ask exactly the same question of the data.
+#'
+#' @param pda_df A dataframe of extracted PDA records.
+#' @param prefix A column-name prefix identifying the program (`"^ia_"` or
+#'   `"^pa_"`).
+#' @return A logical vector with one element per row of `pda_df`, `FALSE`
+#'   throughout where the program has no measurement columns at all.
+#' @noRd
+states_any_program_value = function(pda_df, prefix) {
+  columns = program_measure_columns(pda_df) %>%
+    purrr::keep(~ stringr::str_detect(.x, prefix)) %>%
+    purrr::discard(~ .x %in% names(pda_indicator_ranges()))
+
+  if (length(columns) == 0) { return(rep(FALSE, nrow(pda_df))) }
+
+  ## A value of exactly zero is treated as stating nothing: a report whose
+  ## request did not cover the program sometimes prints "$0" or "0" against a
+  ## field (FEMA-DR-WI "Lack of Snow" prints an ICC ratio of 0 and a $0 total
+  ## estimate among all-dash placeholders), and a report that measured a
+  ## program never reports every figure as zero.
+  columns %>%
+    purrr::map(~ !is.na(pda_df[[.x]]) & pda_df[[.x]] != 0) %>%
+    purrr::reduce(`|`)
+}
+
+#' Settle whether a program was requested when the report contradicts itself
+#'
+#' `ia_requested` and `pa_requested` are read from the summary section, which
+#' states "Individual Assistance - Not requested" or the equivalent. A handful of
+#' reports say that and then print a full set of values for the program anyway. 
+#' Where that happens the report's opening narrative
+#' decides it: every report begins with a sentence of the form "The Governor
+#' requested a declaration for Public Assistance for 17 counties and Hazard
+#' Mitigation for the entire Commonwealth", and it is written independently of
+#' the summary table. 
+#'
+#' A summary reading "not requested in appeal" is treated as not requested. An
+#' appealed disaster is finally decided on the appeal, so the appeal's scope is
+#' the one that matters.
+#'
+#' @param pda_df A dataframe of extracted PDA records.
+#' @return `pda_df` with the two flags settled and a `requested_from_narrative`
+#'   column naming any program whose flag the narrative changed.
+#' @noRd
+resolve_requested_flags = function(pda_df) {
+
+  required = c("text", "ia_requested", "pa_requested")
+  if (!all(required %in% names(pda_df))) { return(pda_df) }
+
+  resolved = pda_df %>%
+    dplyr::mutate(
+      ## Every sentence about the request, taken from the narrative that precedes
+      ## the summary tables, or from the whole report where that header does not
+      ## appear. Matching whole sentences rather than one fixed
+      ## opening phrase covers the reports that write "The Governor requested
+      ## Public Assistance program for five areas and Hazard Mitigation
+      ## statewide", which names no "declaration for" at all.
+      request_sentence = stringr::str_extract(
+          text, "^.*?(?=Summary of Damage Assessment)") %>%
+        dplyr::coalesce(text) %>%
+        dplyr::coalesce("") %>%
+        stringr::str_extract_all("[^.]*\\brequest(ed|ing|s)?\\b[^.]*\\.") %>%
+        purrr::map_chr(stringr::str_c, collapse = " ") %>%
+        dplyr::na_if(""),
+      ## A request for any component program of Individual Assistance counts as
+      ## a request for Individual Assistance.
+      narrative_requests_ia = stringr::str_detect(
+        dplyr::coalesce(request_sentence, ""),
+        stringr::regex(
+          stringr::str_c(
+            "Individual Assistance|Individuals and Households|",
+            "Crisis Counseling|Disaster Unemployment Assistance|\\bDUA\\b|",
+            "Disaster Legal Services|Disaster Case Management"),
+          ignore_case = TRUE)),
+      narrative_requests_pa = stringr::str_detect(
+        dplyr::coalesce(request_sentence, ""),
+        stringr::regex("Public Assistance", ignore_case = TRUE)),
+      ## A narrative that names no recognized program was not read successfully,
+      ## and is not evidence either way. Small Business Administration loans
+      ## belong to the SBA rather than to FEMA's programs, but a request can
+      ## consist of nothing else, so naming one is a successfully read narrative
+      ## that requests neither Individual nor Public Assistance.
+      narrative_is_readable = stringr::str_detect(
+        dplyr::coalesce(request_sentence, ""),
+        stringr::regex(
+          stringr::str_c(
+            "Individual Assistance|Individuals and Households|",
+            "Public Assistance|Hazard Mitigation|",
+            "Crisis Counseling|Disaster Unemployment Assistance|\\bDUA\\b|",
+            "Disaster Legal Services|Disaster Case Management|",
+            "Small Business Administration|\\bSBA\\b|",
+            "Economic Injury (Disaster )?Loan"),
+          ignore_case = TRUE)),
+      ia_from_narrative =
+        !is.na(ia_requested) & ia_requested == 0 &
+        states_any_program_value(pda_df, "^ia_") & narrative_requests_ia,
+      pa_from_narrative =
+        !is.na(pa_requested) & pa_requested == 0 &
+        states_any_program_value(pda_df, "^pa_") & narrative_requests_pa,
+      ia_not_from_narrative =
+        !is.na(ia_requested) & ia_requested == 1 & narrative_is_readable &
+        !states_any_program_value(pda_df, "^ia_") & !narrative_requests_ia,
+      pa_not_from_narrative =
+        !is.na(pa_requested) & pa_requested == 1 & narrative_is_readable &
+        !states_any_program_value(pda_df, "^pa_") & !narrative_requests_pa,
+      ia_requested = dplyr::case_when(
+        ia_from_narrative ~ 1,
+        ia_not_from_narrative ~ 0,
+        TRUE ~ ia_requested),
+      pa_requested = dplyr::case_when(
+        pa_from_narrative ~ 1,
+        pa_not_from_narrative ~ 0,
+        TRUE ~ pa_requested),
+      ia_settled = ia_from_narrative | ia_not_from_narrative,
+      pa_settled = pa_from_narrative | pa_not_from_narrative,
+      requested_from_narrative = dplyr::case_when(
+        ia_settled & pa_settled ~ "ia; pa",
+        ia_settled ~ "ia",
+        pa_settled ~ "pa",
+        TRUE ~ NA_character_))
+
+  resolved %>%
+    dplyr::select(
+      -request_sentence,
+      -narrative_requests_ia, -narrative_requests_pa,
+      -narrative_is_readable,
+      -ia_from_narrative, -pa_from_narrative,
+      -ia_not_from_narrative, -pa_not_from_narrative,
+      -ia_settled, -pa_settled)
+}
+
 #' Run quality checks over the assembled PDA dataset
 #'
 #' Every field in this dataset is read out of an unstructured PDF by pattern
@@ -920,28 +947,25 @@ pda_indicator_ranges = function() {
 #' it silently produces a wrong value or an empty column. These checks look for
 #' the shapes that failure takes -- a value that cannot be what the field
 #' measures, a footnote marker standing in for a dollar total, a column that
-#' matched nothing at all -- and report them, so that a broken pattern is
+#' matched nothing at all -- and record them, so that a broken pattern is
 #' visible when the dataset is built rather than after it has been published.
 #'
-#' Definite errors are raised as a single `warning()` listing every problem
-#' found. Descriptive counts that need a human judgment rather than a rule --
-#' the missingness of each field among the reports that should state it -- are
-#' reported with `message()`.
-#'
-#' Nothing is modified. Values are left as parsed so that a problem can be
+#' Values are left as parsed so that a problem can be
 #' investigated against the source report, rather than being replaced by `NA`
-#' and losing the evidence.
+#' and losing the evidence. Each record's problems are written to a `warnings`
+#' column (`NA` where none were found); dataset-wide problems, which belong to
+#' no single record, are attached as the `"dataset_issues"` attribute. Nothing
+#' is printed here -- `get_preliminary_damage_assessments()` reports the counts
+#' in a single consolidated warning.
 #'
 #' @param pda_df A dataframe of extracted PDA records.
-#' @return `pda_df`, invisibly and unchanged.
+#' @return `pda_df` with a `warnings` column added, carrying the
+#'   `"dataset_issues"` attribute.
 #' @noRd
 check_pda_quality = function(pda_df) {
 
   ## a value this many times the median of a column's non-zero values is
-  ## reported as an outlier. The archive's most extreme genuine values sit
-  ## around 60 times their column median (a 537 million dollar Public
-  ## Assistance estimate against an 8.6 million median), so 100 flags the
-  ## mis-parses without reporting the largest real disasters.
+  ## reported as an outlier.
   outlier_multiple = 100
 
   ## a column emptier than this among the reports that should state it is
@@ -950,99 +974,91 @@ check_pda_quality = function(pda_df) {
   ## reports because older report layouts do not contain them at all.
   empty_column_threshold = 0.95
 
-  issues = character(0)
-  note = function(...) { issues <<- c(issues, stringr::str_c(...)) }
+  ## one character vector of problems per record
+  row_issues = rep(list(character(0)), nrow(pda_df))
 
-  has = function(column) { column %in% names(pda_df) && is.numeric(pda_df[[column]]) }
+  dataset_issues = character(0)
+  note_dataset = function(...) {
+    dataset_issues <<- c(dataset_issues, stringr::str_c(...)) }
 
-  ## counts, dollars, percentages, and ratios; the 0/1 flags and the identity
-  ## columns are excluded because the checks below do not describe them
-  flag_columns = c(
-    "event_native_flag", "ia_requested", "pa_requested",
-    "pa_preemptive_declaration")
+  ## appends a problem description to each flagged record. `texts` is either
+  ## one string for every record or a vector aligned to the rows of `pda_df`,
+  ## so a description can quote the record's own offending value.
+  flag_rows = function(is_problem, texts) {
+    rows = which(dplyr::coalesce(is_problem, FALSE))
+    if (length(rows) == 0) { return(invisible(NULL)) }
+    if (length(texts) == 1) { texts = rep(texts, nrow(pda_df)) }
+    for (row in rows) {
+      row_issues[[row]] <<- c(row_issues[[row]], texts[row]) } }
 
-  measure_columns = names(pda_df) %>%
-    purrr::discard(~ .x %in% c(non_extracted_columns(), flag_columns, "parser_version")) %>%
-    purrr::keep(~ is.numeric(pda_df[[.x]]))
+  has = function(column) { column %in% names(pda_df) && is.numeric(pda_df[[column]]) }
+
+  measure_columns = program_measure_columns(pda_df)
 
   percent_columns = measure_columns %>% purrr::keep(~ stringr::str_detect(.x, "percent$"))
 
-  ## reports the rows behind a count, so a problem can be traced back to the
-  ## source PDF rather than only counted
-  example_reports = function(is_problem, limit = 3) {
-    paths = pda_df$path[which(is_problem)]
-    if (length(paths) == 0) { return("") }
-    stringr::str_c(
-      " (e.g. ",
-      stringr::str_c(basename(utils::head(paths, limit)), collapse = ", "),
-      ")") }
-
-  ## 1. Values that are not finite numbers. Inf and -Inf are what max() and
-  ## min() return over an empty vector, so they mark a row where nothing was
-  ## extracted rather than a genuinely extreme value, and they propagate
-  ## silently through any later arithmetic.
+  ## values that can be compared against a threshold at all
+  is_usable = function(x) { !is.na(x) & is.finite(x) }
+
+  ## 1. Values that are not finite numbers.
   purrr::walk(measure_columns, function(column) {
     x = pda_df[[column]]
-    n_bad = sum(!is.na(x) & !is.finite(x))
-    if (n_bad > 0) {
-      note(
-        n_bad, " value(s) of ", column, " are Inf or NaN rather than numbers",
-        example_reports(!is.na(x) & !is.finite(x)),
-        ". These are usually the result of summarising an empty set of matches ",
-        "and should be NA.") } })
-
-  ## 2. Negative values. Every measure here is a count, a dollar amount, a
-  ## share, or a ratio, none of which can fall below zero.
+    flag_rows(
+      !is.na(x) & !is.finite(x),
+      stringr::str_c(column, " is Inf or NaN rather than a number")) })
+
+  ## 2. Negative values.
   purrr::walk(measure_columns, function(column) {
     x = pda_df[[column]]
-    is_negative = !is.na(x) & is.finite(x) & x < 0
-    if (any(is_negative)) {
-      note(
-        sum(is_negative), " value(s) of ", column, " are negative (minimum ",
-        min(x[is_negative]), ")", example_reports(is_negative),
-        ", which this field cannot be.") } })
+    flag_rows(
+      is_usable(x) & x < 0,
+      stringr::str_c(
+        column, " is negative (", x, "); this field cannot hold a value ",
+        "below zero")) })
 
   ## 3. Percentages outside 0-100. drop_impossible_percentages() sets these to
   ## NA when the dataset is generated, so anything found here came from a
   ## cached file written before that step existed.
   purrr::walk(percent_columns, function(column) {
     x = pda_df[[column]]
-    is_impossible = !is.na(x) & is.finite(x) & (x < 0 | x > 100)
-    if (any(is_impossible)) {
-      note(
-        sum(is_impossible), " value(s) of ", column, " fall outside 0-100 ",
-        "(maximum ", max(x[is_impossible]), ")", example_reports(is_impossible),
-        ". The text extracted for these was not the intended figure.") } })
+    flag_rows(
+      is_usable(x) & (x < 0 | x > 100),
+      stringr::str_c(
+        column, " (", x, ") falls outside 0-100; the text extracted was not ",
+        "the intended figure")) })
 
   ## 4. Dollar totals small enough to be a footnote marker rather than a cost.
   dollars = pda_dollar_columns()
   purrr::walk(dollars$columns, function(column) {
     if (!has(column)) { return(invisible(NULL)) }
     x = pda_df[[column]]
-    is_too_small = !is.na(x) & is.finite(x) & x > 0 & x < dollars$floor
-    if (any(is_too_small)) {
-      note(
-        sum(is_too_small), " value(s) of ", column, " are under $",
-        dollars$floor, " (observed: ",
-        stringr::str_c(sort(unique(x[is_too_small])), collapse = ", "), ")",
-        example_reports(is_too_small),
-        ". A total this small is almost certainly the label's footnote number ",
-        "rather than a cost estimate.") } })
+    flag_rows(
+      is_usable(x) & x > 0 & x < dollars$floor,
+      stringr::str_c(
+        column, " (", x, ") is under $", dollars$floor, ", almost certainly ",
+        "the label's footnote number rather than a cost estimate")) })
 
   ## 5. Statutory per capita thresholds outside their published range, which
   ## most often means the statewide and countywide values were swapped.
-  purrr::iwalk(pda_indicator_ranges(), function(range, column) {
+  ##
+  ## The statewide threshold is exempt. `impute_statewide_indicator()` replaces
+  ## an out-of-range value there with the one the rest of its fiscal year states,
+  ## so by the time the data is returned the problem has been corrected and a
+  ## warning would describe a value the caller never sees. The countywide
+  ## threshold is still checked, because nothing corrects it.
+  checked_ranges = pda_indicator_ranges() %>%
+    purrr::discard_at("pa_per_capita_impact_indicator_statewide")
+
+  purrr::iwalk(checked_ranges, function(range, column) {
     if (!has(column)) { return(invisible(NULL)) }
     x = pda_df[[column]]
-    is_outside = !is.na(x) & is.finite(x) & (x < range[1] | x > range[2])
-    if (any(is_outside)) {
-      note(
-        sum(is_outside), " value(s) of ", column, " fall outside the published ",
-        "range of ", range[1], "-", range[2], " dollars (observed: ",
-        stringr::str_c(sort(unique(x[is_outside])), collapse = ", "), ")",
-        example_reports(is_outside),
-        ". This field is a statutory threshold, so a value outside that range ",
-        "is a mis-extraction -- commonly the other geography's threshold.") } })
+    flag_rows(
+      is_usable(x) & (x < range[1] | x > range[2]),
+      stringr::str_c(
+        column, " (", x, ") falls outside the published range of ", range[1],
+        "-", range[2], " dollars; this field is a statutory threshold, so a ",
+        "value outside that range is a mis-extraction -- commonly the other ",
+        "geography's threshold")) })
 
   ## 6. Damage categories that do not add up. FEMA reports the four severity
   ## categories as a breakdown of the impacted total, so their sum cannot
@@ -1069,57 +1085,30 @@ check_pda_quality = function(pda_df) {
       is.finite(component_sum) &
       component_sum > pda_df$ia_residences_impacted * 1.05
 
-    if (any(exceeds_total)) {
-      note(
-        sum(exceeds_total), " report(s) have damage categories summing to more ",
-        "than their stated total of impacted residences",
-        example_reports(exceeds_total),
-        ". At least one of the five figures was read from the wrong field.") } }
+    flag_rows(
+      exceeds_total,
+      stringr::str_c(
+        "the four damage categories sum to more than the stated total of ",
+        "impacted residences; at least one of the five figures was read from ",
+        "the wrong field")) }
 
   ## 7. Individual and Public Assistance values recorded for a program the
-  ## report states was not requested. These cannot both be true, and the usual
-  ## cause is the "Not Requested" wording changing so the flag is wrong.
-  ##
-  ## The two statutory per capita thresholds are excluded. They are reference
-  ## values FEMA prints in every report's summary table whether or not Public
-  ## Assistance was requested -- a report reading "Public Assistance - Not
-  ## requested" still states "Statewide per capita impact indicator: $1.29" --
-  ## so their presence says nothing about what was requested. Counting them
-  ## reported 148 contradictions where only 7 rows held an actual Public
-  ## Assistance measurement.
+  ## report states was not requested.
   purrr::iwalk(
     list(ia_requested = "^ia_", pa_requested = "^pa_"),
     function(prefix, flag) {
       if (!has(flag)) { return(invisible(NULL)) }
-      program_columns = measure_columns %>%
-        purrr::keep(~ stringr::str_detect(.x, prefix)) %>%
-        purrr::discard(~ .x %in% names(pda_indicator_ranges()))
-      if (length(program_columns) == 0) { return(invisible(NULL)) }
-
-      has_any_value = program_columns %>%
-        purrr::map(~ !is.na(pda_df[[.x]])) %>%
-        purrr::reduce(`|`)
 
-      contradicts = !is.na(pda_df[[flag]]) & pda_df[[flag]] == 0 & has_any_value
-      if (any(contradicts)) {
-        note(
-          sum(contradicts), " report(s) carry values for a program that ", flag,
-          " records as not requested", example_reports(contradicts),
-          ". Either the flag or the values are wrong.") } })
+      flag_rows(
+        !is.na(pda_df[[flag]]) & pda_df[[flag]] == 0 &
+          states_any_program_value(pda_df, prefix),
+        stringr::str_c(
+          "the report carries values for a program that ", flag, " records ",
+          "as not requested; either the flag or the values are wrong")) })
 
   ## 8. Demographic shares of exactly zero. No populated jurisdiction has no
   ## residents over 65, no children, nobody in poverty, or no unemployment, so
   ## a zero here is not a credible measurement.
-  ##
-  ## There are two causes and the check cannot tell them apart, so it reports
-  ## the value and leaves the judgment to a person. Most were a field the
-  ## report left blank, where the dash placeholder was stripped and the next
-  ## label's footnote number read in its place; the cleanup in
-  ## `extract_pda_attributes()` now discards those, which removed 255 of the
-  ## 258 zeros this check originally found. The three that remain are printed
-  ## as "0.00%" in the source document, so the extraction is faithful and the
-  ## implausible figure is FEMA's own.
-  ##
   ## Insurance coverage shares are excluded because a report can genuinely
   ## state that none of the impacted residences carried flood insurance.
   zero_impossible_columns = c(
@@ -1131,82 +1120,82 @@ check_pda_quality = function(pda_df) {
 
   purrr::walk(zero_impossible_columns, function(column) {
     x = pda_df[[column]]
-    is_zero = !is.na(x) & x == 0
-    if (any(is_zero)) {
-      note(
-        sum(is_zero), " value(s) of ", column, " are exactly zero",
-        example_reports(is_zero),
-        ". A share of zero is not a credible value for this measure. Check the ",
-        "source report: either it left the field blank and a footnote number ",
-        "was read in its place, or it prints a zero that is itself wrong.") } })
+    flag_rows(
+      !is.na(x) & x == 0,
+      stringr::str_c(
+        column, " is exactly zero, which is not a credible value for this ",
+        "measure; either the field was blank and a footnote number was read ",
+        "in its place, or the report prints a zero that is itself wrong")) })
 
   ## 9. Single values far above the rest of their column.
   purrr::walk(measure_columns, function(column) {
     x = pda_df[[column]]
-    usable = x[!is.na(x) & is.finite(x) & x > 0]
-    if (length(usable) < 30) { return(invisible(NULL)) }
-    ceiling_value = stats::median(usable) * outlier_multiple
-    is_outlier = !is.na(x) & is.finite(x) & x > ceiling_value
-    if (any(is_outlier)) {
-      note(
-        sum(is_outlier), " value(s) of ", column, " exceed ", outlier_multiple,
-        " times the column median (median ", stats::median(usable),
-        ", maximum observed ", max(x[is_outlier]), ")",
-        example_reports(is_outlier),
-        ". Check these against the source reports before publishing.") } })
-
-  ## 10. Disaster numbers that are not four digits. An approved request always
-  ## receives one; a denied request never does, so only approvals are checked
-  ## for absence.
+    usable_values = x[is_usable(x) & x > 0]
+    if (length(usable_values) < 30) { return(invisible(NULL)) }
+    flag_rows(
+      is_usable(x) & x > stats::median(usable_values) * outlier_multiple,
+      stringr::str_c(
+        column, " (", x, ") exceeds ", outlier_multiple, " times the ",
+        "column's median of ", stats::median(usable_values), "; check it ",
+        "against the source report")) })
+
+  ## 10. Disaster numbers that are not four digits.
   if ("disaster_number" %in% names(pda_df)) {
     numbers = as.character(pda_df$disaster_number)
-    is_malformed = !is.na(numbers) & !stringr::str_detect(numbers, "^[0-9]{4}$")
-    if (any(is_malformed)) {
-      note(
-        sum(is_malformed), " disaster number(s) are not four digits (",
-        stringr::str_c(sort(unique(numbers[is_malformed])), collapse = ", "),
-        ")", example_reports(is_malformed), ".") }
+    flag_rows(
+      !is.na(numbers) & !stringr::str_detect(numbers, "^[0-9]{4}$"),
+      stringr::str_c("disaster number ", numbers, " is not four digits"))
+
+    if ("event_type" %in% names(pda_df)) {
+      flag_rows(
+        stringr::str_detect(pda_df$event_type, "approv") & is.na(numbers),
+        stringr::str_c(
+          "the report has no disaster number, though an approved request is ",
+          "always assigned one")) }
 
+    ## a disaster number mapping to more than one approved report means at
+    ## least one of them carries the wrong number
     if ("event_type" %in% names(pda_df)) {
-      missing_on_approval =
-        stringr::str_detect(pda_df$event_type, "approv") & is.na(numbers)
-      if (any(missing_on_approval)) {
-        note(
-          sum(missing_on_approval), " approved report(s) have no disaster ",
-          "number", example_reports(missing_on_approval),
-          ", though an approved request is always assigned one.") } } }
+      approved_numbers = numbers[
+        stringr::str_detect(pda_df$event_type, "approv") & !is.na(numbers)]
+      shared = unique(approved_numbers[duplicated(approved_numbers)])
+      flag_rows(
+        stringr::str_detect(pda_df$event_type, "approv") &
+          !is.na(numbers) & numbers %in% shared,
+        stringr::str_c(
+          "disaster number ", numbers, " maps to more than one approved PDA ",
+          "report and is likely incorrect on at least one of them")) } }
 
   ## 11. Determination dates outside the period the archive covers. FEMA's
   ## earliest published report is from 2007, and a date in the future is a
   ## misread year.
   if ("event_date_determined" %in% names(pda_df)) {
     dates = suppressWarnings(as.Date(pda_df$event_date_determined))
-    is_implausible =
-      !is.na(dates) & (dates < as.Date("2000-01-01") | dates > Sys.Date() + 1)
-    if (any(is_implausible)) {
-      note(
-        sum(is_implausible), " determination date(s) fall outside 2000 to ",
-        "today (", stringr::str_c(sort(unique(as.character(dates[is_implausible]))), collapse = ", "),
-        ")", example_reports(is_implausible), ".") } }
+    flag_rows(
+      !is.na(dates) & (dates < as.Date("2000-01-01") | dates > Sys.Date() + 1),
+      stringr::str_c(
+        "the determination date (", as.character(dates), ") falls outside ",
+        "2000 to today, so its year was misread")) }
 
   ## 12. The same source PDF parsed into more than one row.
   if ("path" %in% names(pda_df)) {
-    duplicated_paths = unique(pda_df$path[duplicated(pda_df$path)])
-    if (length(duplicated_paths) > 0) {
-      note(
-        length(duplicated_paths), " source report(s) appear on more than one ",
-        "row: ", stringr::str_c(basename(duplicated_paths), collapse = ", "),
-        ".") } }
+    flag_rows(
+      pda_df$path %in% unique(pda_df$path[duplicated(pda_df$path)]),
+      "this source PDF parsed into more than one row") }
+
+  ## 13. A report that disagreed with itself about whether a program was
+  ## requested, settled from its opening narrative by
+  ## `resolve_requested_flags()`.
+  if ("requested_from_narrative" %in% names(pda_df)) {
+    flag_rows(
+      !is.na(pda_df$requested_from_narrative),
+      stringr::str_c(
+        "the report disagrees with itself about whether ",
+        pda_df$requested_from_narrative, " was requested; the flag was ",
+        "settled from the opening narrative")) }
 
-  ## 13. Columns that are empty, or nearly so, among the reports that should
-  ## state them. This is the signature of a pattern that no longer matches the
-  ## documents, which is otherwise indistinguishable from a field FEMA simply
-  ## does not report.
-  ##
-  ## The denominator is what makes the check meaningful: an Individual
-  ## Assistance field is expected to be missing wherever Individual Assistance
-  ## was not requested, so only reports that requested the program and were
-  ## approved are counted. The same holds for Public Assistance.
+  ## 14. Columns that are empty, or nearly so, among the reports that should
+  ## state them. This belongs to the dataset, not to any one record.
   relevant_rows = function(prefix) {
     flag = stringr::str_c(stringr::str_remove(prefix, "\\^"), "requested")
     if (!has(flag) || !"event_type" %in% names(pda_df)) { return(rep(TRUE, nrow(pda_df))) }
@@ -1230,7 +1219,7 @@ check_pda_quality = function(pda_df) {
       dplyr::filter(share_missing >= empty_column_threshold)
 
     if (nrow(empty_columns) > 0) {
-      note(
+      note_dataset(
         nrow(empty_columns), " column(s) are at least ",
         round(empty_column_threshold * 100), "% missing among the reports that ",
         "requested the program and were approved, which usually means the ",
@@ -1240,42 +1229,21 @@ check_pda_quality = function(pda_df) {
           round(empty_columns$share_missing * 100, 1), "% of ",
           empty_columns$n_relevant, ")",
           collapse = "; "),
-        ".") }
-
-    message(
-      "Missingness among reports that requested the program and were approved:\n",
-      stringr::str_c(
-        "  ", missingness$column, ": ",
-        round(missingness$share_missing * 100, 1), "% of ",
-        missingness$n_relevant,
-        collapse = "\n")) }
-
-  if (length(issues) > 0) {
-    warning(
-      stringr::str_c(
-        length(issues), " quality problem(s) found in the preliminary damage ",
-        "assessment data. Values are returned as parsed, so each can be checked ",
-        "against its source report:\n",
-        stringr::str_c("  ", seq_along(issues), ". ", issues, collapse = "\n")),
-      call. = FALSE) }
+        ".") } }
 
-  invisible(pda_df)
+  checked = pda_df %>%
+    dplyr::mutate(warnings = purrr::map_chr(
+      row_issues,
+      ~ if (length(.x) == 0) { NA_character_ } else {
+        stringr::str_c(.x, collapse = "; ") }))
+  attr(checked, "dataset_issues") = dataset_issues
+  checked
 }
 
 #' Correct disaster numbers shared by multiple, genuinely different PDA reports
 #'
-#' A handful of PDAs carry a typo'd (or, for FEMA's newest filename convention,
-#' absent) disaster number, which surfaces as two different reports sharing one
-#' `disaster_number`. The number printed in the report body (`FEMA-XXXX`) is
-#' authoritative, so for any `disaster_number` duplicated across reports we
-#' re-derive it from the text. A lenient `FEMA-XXXX` match is used -- rather than
-#' requiring the `-DR` suffix, as the per-file extraction does -- because the cases
-#' that slip through to become duplicates are exactly those where `-DR` is missing
-#' or mangled in the text. The correction is guarded to non-`NA`, already-duplicated
-#' numbers, so it only ever replaces a wrong number and never fills an `NA` (many
-#' denied requests never receive an official number, and their filename-derived
-#' value is our best guess). Duplication is undetectable per-file, so this must run
-#' on the full combined dataset.
+#' A handful of PDAs carry a typo'd or absent disaster number, which surfaces as
+#' two different reports sharing one `disaster_number`.
 #'
 #' @param pda_df A dataframe of extracted PDA records (must contain `text` and
 #'   `disaster_number`).
@@ -1307,8 +1275,7 @@ correct_duplicate_disaster_numbers = function(pda_df) {
   ## evidently copied from another document, which lands two unrelated disasters
   ## on one number. Where a duplicated number disagrees with the number in that
   ## report's own filename, and the filename's number is claimed by no other
-  ## report, the filename is preferred -- it is the only remaining independent
-  ## evidence, and an unclaimed number cannot itself create a new collision.
+  ## report, the filename is preferred.
   if (!"disaster_number_filename" %in% names(corrected)) { return(corrected) }
 
   claimed = corrected$disaster_number[!is.na(corrected$disaster_number)]
@@ -1326,66 +1293,849 @@ correct_duplicate_disaster_numbers = function(pda_df) {
     dplyr::select(-disaster_number_count)
 }
 
-#' Warn about disaster numbers shared by multiple approved PDA reports
+#' A regular expression matching any state, territory, or District name
+#'
+#' @return A length-one character regular expression.
+#' @noRd
+state_name_pattern = function() {
+  names_longest_first = tidycensus::fips_codes %>%
+    dplyr::distinct(state_name) %>%
+    dplyr::arrange(dplyr::desc(stringr::str_length(state_name))) %>%
+    dplyr::pull(state_name) %>%
+    stringr::str_c(collapse = "|")
+
+  stringr::str_c("\\b(?:", names_longest_first, ")\\b")
+}
+
+#' Keyword patterns defining the shared set of hazard categories
+#'
+#' PDA titles and FEMA's own denial records both describe the hazard in free
+#' text, and they do not use the same words for the same thing ("Severe Storms
+#' and Flooding" against "Flood, Severe Storm(s)"). Each pattern below maps the
+#' wordings observed in both sources onto one category name, so that a hazard
+#' set derived from a PDA can be compared against one derived from a FEMA
+#' record. The category names are the values written into the `hazards` and
+#' `denial_hazards` columns.
+#'
+#' @return A named character vector: names are category labels, values are
+#'   case-insensitive regular expressions.
+#' @noRd
+hazard_category_patterns = function() {
+  c(
+    "flooding" = "flood|flash flood|high water",
+    "severe storm" = "severe storm|thunderstorm|straight-line wind|straight line wind|high wind|\\bwinds?\\b|hail|rainstorm|severe weather",
+    "tornado" = "tornado",
+    "hurricane" = "hurricane|typhoon",
+    ## FEMA abbreviates a named tropical system to "TS Cristobal" in its own
+    ## records, which no spelled-out pattern reaches
+    "tropical storm" = "tropical storm|tropical depression|tropical cyclone|\\bts\\b",
+    "coastal storm" = "coastal storm|storm surge|nor'?easter",
+    "winter storm" = "winter storm|winter weather|snow|ice storm|blizzard|freez|extreme cold",
+    "wildfire" = "wildfire|\\bfires?\\b",
+    "landslide" = "landslide|mudslide|mudflow|debris flow",
+    "earthquake" = "earthquake|seismic",
+    "tsunami" = "tsunami",
+    "volcanic eruption" = "volcan|lava",
+    "drought" = "drought",
+    "extreme heat" = "extreme heat|heat wave",
+    "dam or levee failure" = "dam failure|levee failure|dam or levee",
+    "pandemic" = "covid|coronavirus|pandemic|epidemic")
+}
+
+#' Assign hazard categories to free-text event descriptions
+#'
+#' @param descriptions A character vector of event titles or incident-type text.
+#' @return A character vector the same length as `descriptions`, each element a
+#'   semicolon-separated set of matched category names, or `NA` where no
+#'   keyword matched.
+#' @noRd
+extract_hazard_categories = function(descriptions) {
+  patterns = hazard_category_patterns()
+
+  purrr::map_chr(
+    stringr::str_to_lower(dplyr::coalesce(descriptions, "")),
+    function(description) {
+      categories_detected = names(patterns)[stringr::str_detect(description, patterns)]
+      if (length(categories_detected) == 0) {
+        NA_character_
+      } else {
+        stringr::str_c(categories_detected, collapse = "; ") } })
+}
+
+#' Hazard categories that name the same event in different words
+#'
+#' @return A named character vector mapping a category to its group.
+#' @noRd
+hazard_equivalent_categories = function() {
+  c("tropical storm" = "tropical or coastal storm",
+    "coastal storm" = "tropical or coastal storm")
+}
+
+#' Count the hazard categories two descriptions share
+#'
+#' @param categories_one,categories_two Character vectors of semicolon-separated
+#'   category sets, as produced by `extract_hazard_categories()`.
+#' @return An integer vector of shared-category counts, `NA` where either side
+#'   has no assigned category.
+#' @noRd
+shared_hazard_category_count = function(categories_one, categories_two) {
+  equivalents = hazard_equivalent_categories()
+  ## categories that name the same event are compared under one name, so the
+  ## count is of distinct events described in common rather than of words shared
+  as_groups = function(categories) {
+    unique(dplyr::coalesce(unname(equivalents[categories]), categories)) }
+
+  purrr::map2_int(
+    stringr::str_split(categories_one, "; "),
+    stringr::str_split(categories_two, "; "),
+    function(set_one, set_two) {
+      if (any(is.na(set_one)) || any(is.na(set_two))) { return(NA_integer_) }
+      length(intersect(as_groups(set_one), as_groups(set_two))) })
+}
+
+#' Add the state name, cleaned event title, and hazard categories to PDA records
+#'
+#' The state is the first state, territory, or District name appearing anywhere
+#' in the report text; FEMA does not print it as a labelled field. The event
+#' title as extracted is the report's heading.
+#' The hazard categories are then read from that cleaned description.
+#'
+#' @param pda_df A dataframe of extracted PDA records (must contain `text` and
+#'   `event_title`).
+#' @return `pda_df` with `state_name` and `hazards` added and `event_title`
+#'   cleaned.
+#' @noRd
+add_pda_derived_columns = function(pda_df) {
+  state_pattern = state_name_pattern()
+  dashes = "-\\u2010-\\u2015\\u2212"
+
+  pda_df %>%
+    dplyr::mutate(
+      state_name = dplyr::coalesce(
+        stringr::str_extract(event_title, state_pattern),
+        stringr::str_extract(text, state_pattern)),
+      event_title = event_title %>%
+        stringr::str_remove_all(stringr::regex(
+          "Preliminary Damage Assessments?( Reports?)?", ignore_case = TRUE)) %>%
+        stringr::str_remove_all(stringr::regex("\\bPDA Reports?\\b", ignore_case = TRUE)) %>%
+        stringr::str_remove_all(stringr::str_c("\\((", state_pattern, ")\\)")) %>%
+        stringr::str_remove("^[^A-Za-z0-9]+") %>%
+        stringr::str_remove(stringr::regex(
+          "^\\s*(the\\s+)?(State|Commonwealth|Territory|District)\\s+of\\s+", ignore_case = TRUE)) %>%
+        stringr::str_remove(stringr::str_c(
+          "^\\s*(", state_pattern, ")",
+          "(?!\\s+(County|City|Parish|Borough|Township)\\b)",
+          "\\s*([", dashes, ",]|\\b)")) %>%
+        stringr::str_remove(stringr::str_c("[", dashes, ",]\\s*(", state_pattern, ")\\s*$")) %>%
+        ## the declaration number and the decision and its date are recorded in
+        ## their own columns (`disaster_number`, `event_type`,
+        ## `event_date_determined`), so the copies the heading carries are removed
+        stringr::str_remove_all(stringr::regex(
+          "FEMA[-\\s]?[0-9]{4}[-\\s]*DR", ignore_case = TRUE)) %>%
+        stringr::str_remove_all(stringr::regex(
+          "(Denial|Denied|Declared|Approved)\\s*(of Appeal|on)?\\s*(January|February|March|April|May|June|July|August|September|October|November|December)?\\s*[0-9]{0,2},?\\s*[0-9]{0,4}",
+          ignore_case = TRUE)) %>%
+        ## collapse the separators left behind by the removals above
+        stringr::str_replace_all(stringr::str_c("(\\s*[", dashes, "]\\s*){2,}"), " - ") %>%
+        stringr::str_remove("^[^A-Za-z0-9]+") %>%
+        stringr::str_remove(stringr::str_c("[\\s", dashes, ",;:.]+$")) %>%
+        stringr::str_squish(),
+      hazards = extract_hazard_categories(event_title))
+}
+
+#' Hand-checked links between denial PDA reports and FEMA denial records
+#'
+#' A denied request has no disaster number, so the automatic passes match on the
+#' decision date. Where two of a state's requests were decided on the same day
+#' and FEMA's names for them carry nothing that ties either to its report, no
+#' rule can separate them, and there are few enough such cases to settle by
+#' hand.
+#'
+#' @return A tibble of `pda_file`, `denial_id`, and `note`.
+#' @noRd
+manual_pda_denial_links = function() {
+  tibble::tribble(
+    ~pda_file, ~denial_id, ~note,
+
+    "PDAReportDenialOST.pdf",
+    "South Dakota | 2018-09-18 | OST severe storm 07/27/2018",
+    "Both South Dakota requests were turned down on 2018-09-18. FEMA abbreviates the Oglala Sioux Tribe to 'OST' in the incident name; the report is the Oglala Sioux Tribe's.",
+
+    "PDAReportDenialCRST.pdf",
+    "South Dakota | 2018-09-18 | SD - Severe Storms 07/04/2018",
+    "The other of the two same-day South Dakota denials, left for the Cheyenne River Sioux Tribe once the Oglala Sioux Tribe claims the denial naming it.")
+}
+
+#' Fill in the statutory statewide per capita indicator where a report omits it
+#'
+#' The indicator is a single national dollar figure, published once for each
+#' federal fiscal year, and every report of that year states the same value: it
+#' does not vary by state, by territory, or by the size of the request.
+#' A stated value outside the published range is treated as missing and replaced,
+#' since it is not the threshold but the countywide figure printed in the
+#' statewide row.
+#'
+#' The fiscal year is taken from the footnote the report prints about itself
+#' ("Statewide Per Capita Impact Indicator for FY20"), falling back to the fiscal
+#' year of the determination date. Those
+#' fills are marked in `pa_per_capita_impact_indicator_statewide_source` so
+#' this function's quality checks can tell them apart; the column is internal,
+#' dropped before the data are returned.
+#'
+#' @param pda_df A dataframe of extracted PDA records.
+#' @return `pda_df` with missing statewide indicators filled where they can be,
+#'   and a `pa_per_capita_impact_indicator_statewide_source` column recording
+#'   which values were read from a report and which were filled in.
+#' @noRd
+impute_statewide_indicator = function(pda_df) {
+
+  plausible_range = pda_indicator_ranges()$pa_per_capita_impact_indicator_statewide
+
+  prepared = pda_df %>%
+    dplyr::mutate(
+      fiscal_year_stated = stringr::str_extract(
+          text,
+          stringr::regex(
+            "Statewide Per Capita Impact Indicator for (FY|Fiscal Year)\\s?[0-9]{2,4}",
+            ignore_case = TRUE)) %>%
+        stringr::str_extract("[0-9]{2,4}$") %>%
+        as.numeric(),
+      ## the footnote abbreviates the year ("FY20"), and one report spells it out
+      fiscal_year_stated = dplyr::if_else(
+        fiscal_year_stated < 100, fiscal_year_stated + 2000, fiscal_year_stated),
+      ## a federal fiscal year begins on 1 October and is named for the calendar
+      ## year it ends in, so a report from November 2019 belongs to FY2020
+      fiscal_year_determined =
+        lubridate::year(event_date_determined) +
+        dplyr::if_else(lubridate::month(event_date_determined) >= 10, 1, 0),
+      fiscal_year = dplyr::coalesce(fiscal_year_stated, fiscal_year_determined))
+
+  indicator_by_fiscal_year = prepared %>%
+    dplyr::filter(
+      !is.na(fiscal_year),
+      !is.na(pa_per_capita_impact_indicator_statewide),
+      dplyr::between(
+        pa_per_capita_impact_indicator_statewide,
+        plausible_range[1], plausible_range[2])) %>%
+    dplyr::count(
+      fiscal_year, pa_per_capita_impact_indicator_statewide,
+      name = "reports_stating_value") %>%
+    ## sorted before the pick so that a year whose two commonest values are
+    ## equally common resolves the same way on every run
+    dplyr::arrange(
+      fiscal_year,
+      dplyr::desc(reports_stating_value),
+      pa_per_capita_impact_indicator_statewide) %>%
+    dplyr::slice_head(n = 1, by = fiscal_year) %>%
+    dplyr::select(
+      fiscal_year,
+      indicator_for_fiscal_year = pa_per_capita_impact_indicator_statewide)
+
+  imputed = prepared %>%
+    dplyr::left_join(
+      indicator_by_fiscal_year, by = "fiscal_year", relationship = "many-to-one") %>%
+    dplyr::mutate(
+      stated_out_of_range =
+        !is.na(pa_per_capita_impact_indicator_statewide) &
+        !dplyr::between(
+          pa_per_capita_impact_indicator_statewide,
+          plausible_range[1], plausible_range[2]),
+      can_impute =
+        (is.na(pa_per_capita_impact_indicator_statewide) | stated_out_of_range) &
+        !is.na(indicator_for_fiscal_year),
+      pa_per_capita_impact_indicator_statewide_source = dplyr::case_when(
+        can_impute & stated_out_of_range ~
+          "imputed, replacing a stated value outside the published range",
+        can_impute & lubridate::month(event_date_determined) %in% 10:12 ~
+          "imputed, and may be one fiscal year too recent",
+        can_impute ~ "imputed",
+        !is.na(pa_per_capita_impact_indicator_statewide) ~ "reported",
+        TRUE ~ NA_character_),
+      pa_per_capita_impact_indicator_statewide = dplyr::if_else(
+        can_impute,
+        indicator_for_fiscal_year,
+        pa_per_capita_impact_indicator_statewide)) %>%
+    dplyr::select(
+      -fiscal_year_stated, -fiscal_year_determined, -fiscal_year,
+      -indicator_for_fiscal_year, -can_impute, -stated_out_of_range)
+
+  ## Not reported to the user directly:
+  ## `pa_per_capita_impact_indicator_statewide_source` records which values
+  ## were filled in and why.
+  imputed
+}
+
+#' Match denied PDA reports to the FEMA denials they describe
+#'
+#' A denied request never receives a disaster number, so a denial PDA cannot be
+#' joined to FEMA's `DeclarationDenials` record by key. What it does carry is
+#' the date the decision was made, which is the denial's `request_status_date`,
+#' so the primary match is an equality join on state and that date. Where one
+#' date matches several of a state's denials -- FEMA can decide two requests
+#' on the same day -- the candidates are narrowed by hazard-category agreement,
+#' then by elimination (a denial claimed by one PDA cannot back another), and
+#' anything still ambiguous is left unmatched rather than guessed at. A PDA with
+#' no same-day denial gets one further chance: the nearest denial within
+#' seven days either side, and only when the hazard categories agree.
 #'
-#' A disaster should map to exactly one approved PDA. Any `disaster_number` shared
-#' by more than one approved report (after `correct_duplicate_disaster_numbers()`)
-#' is incorrect -- a typo the text-based recovery could not resolve, or a
-#' duplicated source file -- and is surfaced for manual review.
+#' Two further passes then run over the reports the state-keyed passes could not
+#' reach at all. A tribal report names the tribe rather than a state, so there is
+#' no state to match on; for those the state is dropped from the key and the date
+#' used alone, but only where exactly one unclaimed denial in the country
+#' shares that date. Tested against the 168 denials the state-keyed pass does
+#' resolve, that rule fires on 133 of them and picks the correct denial in all
+#' 133, and declines on the remaining 35 rather than guessing. What it cannot
+#' settle is two of a state's requests decided on the same day, which is what
+#' `manual_pda_denial_links()` is for.
 #'
-#' @param pda_df A dataframe of extracted PDA records (must contain `event_type`
-#'   and `disaster_number`).
-#' @return `pda_df`, invisibly and unchanged; called for the side effect of a
-#'   `warning()` listing any offending disaster numbers.
+#' @param denied_pdas Denied PDA records, with `state_name`, `decision`,
+#'   `event_date_determined`, and `hazards`.
+#' @param denials FEMA denial records, with `state_name`, `decision`,
+#'   `request_status_date`, `denial_id`, and `denial_hazards`.
+#' @return `denied_pdas` with one row each, plus `denial_id` (`NA` where no
+#'   match was made) and `match_quality`.
 #' @noRd
-warn_approved_disaster_number_duplicates = function(pda_df) {
-  approved_duplicates = pda_df %>%
+match_denied_pdas_to_denials = function(denied_pdas, denials) {
+
+  denied_pdas1 = denied_pdas %>% dplyr::mutate(pda_id = dplyr::row_number())
+  ## the reduced copy is what the state-keyed join in step 1 is allowed to see;
+  ## the full `denials` is kept because the date-only pass below compares event
+  ## titles and so needs `declaration_title` as well
+  denials_keyed = denials %>%
+    dplyr::select(state_name, decision, request_status_date, denial_id, denial_hazards)
+
+  ## step 1: exact match on the denial decision date. The relationship is
+  ## many-to-many only because two same-state denials can share a decision
+  ## date; those ties are resolved in the steps that follow.
+  candidates1 = denied_pdas1 %>%
+    dplyr::left_join(
+      denials_keyed,
+      by = dplyr::join_by(state_name, decision, event_date_determined == request_status_date),
+      relationship = "many-to-many") %>%
+    dplyr::mutate(
+      shared_hazard_count = shared_hazard_category_count(hazards, denial_hazards),
+      hazards_agree = shared_hazard_count > 0,
+      match_quality = dplyr::if_else(
+        is.na(denial_id),
+        NA_character_,
+        "exact: the PDA determination date is the denial decision date"))
+
+  ## step 2: where a PDA matched several same-day denials, drop the candidates
+  ## sharing no hazard category with the PDA, then keep only the candidate(s)
+  ## sharing the most categories (ties survive to step 3). PDAs whose candidates
+  ## were all eliminated are re-attached as unmatched rows.
+  candidates2 = candidates1 %>%
+    dplyr::add_count(pda_id, name = "candidate_count") %>%
+    dplyr::filter(candidate_count == 1 | dplyr::coalesce(hazards_agree, FALSE)) %>%
+    dplyr::filter(
+      dplyr::coalesce(shared_hazard_count, 0L) == max(dplyr::coalesce(shared_hazard_count, 0L)),
+      .by = pda_id) %>%
+    dplyr::bind_rows(dplyr::anti_join(denied_pdas1, ., by = "pda_id"))
+
+  ## step 3: resolve the remaining ties by elimination. A PDA with exactly one
+  ## candidate claims that denial, which
+  ## can in turn leave another PDA with a single candidate. Repeat until nothing
+  ## changes. Two PDAs whose only candidate is the same denial both keep it
+  ## here; step 4 addresses this.
+  candidates3 = local({
+    remaining = candidates2 %>%
+      dplyr::filter(!is.na(denial_id)) %>%
+      dplyr::select(-candidate_count)
+
+    repeat {
+      counted = remaining %>% dplyr::add_count(pda_id, name = "candidates_per_pda")
+      claimed_denial_ids = counted %>%
+        dplyr::filter(candidates_per_pda == 1) %>%
+        dplyr::pull(denial_id)
+      pruned = counted %>%
+        dplyr::filter(candidates_per_pda == 1 | !denial_id %in% claimed_denial_ids) %>%
+        dplyr::select(-candidates_per_pda)
+      if (nrow(pruned) == nrow(remaining)) { break }
+      remaining = pruned }
+
+    dplyr::bind_rows(remaining, dplyr::anti_join(denied_pdas1, remaining, by = "pda_id")) })
+
+  ## step 4: enforce cardinality. A match survives only where the PDA has one
+  ## candidate, the hazards are not known to disagree, and the denial is not
+  ## also claimed by another PDA.
+  resolved = candidates3 %>%
+    dplyr::add_count(pda_id, name = "candidate_count_resolved") %>%
+    dplyr::add_count(denial_id, name = "pdas_per_denial") %>%
+    dplyr::mutate(
+      match_ok =
+        !is.na(match_quality) &
+        candidate_count_resolved == 1 &
+        dplyr::coalesce(hazards_agree, TRUE) &
+        pdas_per_denial == 1)
+
+  ## A report left unmatched here -- its candidate denial ambiguous, or
+  ## describing a different hazard -- is counted in the unmatched total the
+  ## single consolidated warning reports.
+  matched_exactly = resolved %>%
+    dplyr::mutate(
+      denial_id = dplyr::if_else(match_ok, denial_id, NA_character_),
+      match_quality = dplyr::if_else(match_ok, match_quality, NA_character_)) %>%
+    dplyr::slice_head(n = 1, by = pda_id)
+
+  ## step 5: fallback for the PDAs with no same-day denial -- the nearest
+  ## denial of the same hazard type within a week, in either direction. 
+  ## A tie between two equally near denials
+  ## leaves two candidates, which the uniqueness test then refuses.
+  claimed_exactly = stats::na.omit(matched_exactly$denial_id)
+
+  matched_fuzzily = matched_exactly %>%
+    dplyr::filter(is.na(match_quality)) %>%
+    dplyr::select(dplyr::all_of(names(denied_pdas1))) %>%
+    dplyr::inner_join(
+      denials %>% dplyr::filter(!denial_id %in% claimed_exactly),
+      by = dplyr::join_by(state_name, decision),
+      relationship = "many-to-many") %>%
+    dplyr::mutate(
+      days_from_denial = as.numeric(event_date_determined - request_status_date),
+      shared_hazard_count = shared_hazard_category_count(hazards, denial_hazards)) %>%
     dplyr::filter(
-      stringr::str_detect(event_type, "approv"),
-      !is.na(disaster_number)) %>%
-    dplyr::add_count(disaster_number, name = "approved_count") %>%
-    dplyr::filter(approved_count > 1)
+      abs(days_from_denial) <= 7,
+      dplyr::coalesce(shared_hazard_count > 0, FALSE)) %>%
+    dplyr::filter(
+      abs(days_from_denial) == min(abs(days_from_denial)),
+      .by = pda_id) %>%
+    dplyr::add_count(pda_id, name = "candidate_count") %>%
+    dplyr::filter(candidate_count == 1) %>%
+    dplyr::transmute(
+      pda_id,
+      denial_id,
+      match_quality = stringr::str_c(
+        "approximate: no denial shares the PDA determination date, so the ",
+        "nearest denial of the same hazard type was used, recorded by FEMA ",
+        abs(days_from_denial), " day(s) ",
+        dplyr::if_else(days_from_denial > 0, "earlier", "later")))
+
+  resolved_by_state = matched_exactly %>%
+    dplyr::rows_update(matched_fuzzily, by = "pda_id", unmatched = "ignore") %>%
+    dplyr::arrange(pda_id) %>%
+    dplyr::select(dplyr::all_of(names(denied_pdas1)), denial_id, match_quality)
+
+  ## step 6: the date alone, without the state. This reaches only the reports the
+  ## state-keyed passes never had a candidate for. The denial must be the only unclaimed one in
+  ## the country on that date, and must either agree on hazard or share a word
+  ## with the report's title, so a same-day denial from an unrelated request
+  ## cannot be picked up on the date alone.
+  had_state_candidate = candidates1 %>%
+    dplyr::filter(!is.na(denial_id)) %>%
+    dplyr::pull(pda_id) %>%
+    unique()
+
+  eligible_for_date_only = resolved_by_state %>%
+    dplyr::filter(is.na(match_quality), !pda_id %in% had_state_candidate)
+
+  unclaimed = denials %>%
+    dplyr::filter(!denial_id %in% stats::na.omit(resolved_by_state$denial_id))
+
+  matched_by_date = eligible_for_date_only %>%
+    dplyr::select(-denial_id, -match_quality) %>%
+    dplyr::left_join(
+      unclaimed %>%
+        dplyr::select(request_status_date, denial_id, declaration_title, denial_hazards),
+      by = dplyr::join_by(event_date_determined == request_status_date),
+      relationship = "many-to-many") %>%
+    dplyr::add_count(pda_id, name = "candidate_count") %>%
+    dplyr::mutate(
+      shared_hazard_count = shared_hazard_category_count(hazards, denial_hazards),
+      shares_a_word = shared_title_word_count(event_title, declaration_title) > 0,
+      match_ok =
+        !is.na(denial_id) &
+        candidate_count == 1 &
+        (dplyr::coalesce(shared_hazard_count > 0, FALSE) | dplyr::coalesce(shares_a_word, FALSE)),
+      denial_id = dplyr::if_else(match_ok, denial_id, NA_character_),
+      match_quality = dplyr::if_else(
+        match_ok,
+        "exact: the only denial in the country sharing the PDA determination date, matched without the state key because the report names none",
+        NA_character_)) %>%
+    dplyr::slice_head(n = 1, by = pda_id) %>%
+    dplyr::select(dplyr::all_of(names(resolved_by_state)))
+
+  resolved_by_date = resolved_by_state %>%
+    dplyr::rows_update(matched_by_date, by = "pda_id", unmatched = "ignore")
+
+  ## step 7: the hand-checked links, for what no rule can separate
+  resolved_by_date %>%
+    apply_manual_pda_denial_links(denials) %>%
+    dplyr::select(-pda_id)
+}
+
+#' Count the words two event descriptions share
+#'
+#' Used only to confirm that a candidate denial is not unrelated to the report,
+#' so the comparison is deliberately crude: both sides are reduced to lowercase
+#' words, with punctuation, FEMA's region codes, and the words that appear in
+#' every tribal name ("tribe", "band", "nation") removed, since those would make
+#' any two tribal records look alike.
+#'
+#' @param descriptions_one,descriptions_two Character vectors of event titles.
+#' @return An integer vector of shared-word counts, `NA` where either side is
+#'   empty.
+#' @noRd
+shared_title_word_count = function(descriptions_one, descriptions_two) {
+  to_words = function(x) {
+    x %>%
+      stringr::str_to_lower() %>%
+      stringr::str_remove_all("\\br(egion)?\\s?[0-9]{1,2}\\b") %>%
+      stringr::str_replace_all("[^a-z0-9 ]", " ") %>%
+      stringr::str_remove_all(stringr::str_c(
+        "\\b(the|of|and|a|an|tribe|tribes|tribal|band|nation|indians|indian|",
+        "village|native|community|pueblo|rancheria|reservation)\\b")) %>%
+      stringr::str_squish() %>%
+      stringr::str_split(" ") }
+
+  purrr::map2_int(
+    to_words(descriptions_one),
+    to_words(descriptions_two),
+    function(words_one, words_two) {
+      words_one = setdiff(words_one, "")
+      words_two = setdiff(words_two, "")
+      if (length(words_one) == 0 || length(words_two) == 0) { return(NA_integer_) }
+      length(intersect(words_one, words_two)) })
+}
+
+#' Apply the hand-checked report-to-denial links
+#'
+#' Consulted only for reports still unmatched, so a hand-written row can fill a
+#' gap but never displace a match the data itself supports.
+#' 
+#' @param denied_pdas Denied PDA records carrying `denial_id` and
+#'   `match_quality` from the automatic passes.
+#' @param denials FEMA denial records.
+#' @return `denied_pdas` with the hand-checked links applied.
+#' @noRd
+apply_manual_pda_denial_links = function(denied_pdas, denials) {
+
+  links = manual_pda_denial_links()
+  if (nrow(links) == 0) { return(denied_pdas) }
 
-  if (nrow(approved_duplicates) > 0) {
+  checked = links %>%
+    dplyr::mutate(
+      report_exists = pda_file %in% basename(denied_pdas$path),
+      denial_exists = denial_id %in% denials$denial_id,
+      denial_claimed =
+        denial_id %in% stats::na.omit(denied_pdas$denial_id),
+      report_already_matched = pda_file %in% basename(
+        denied_pdas$path[!is.na(denied_pdas$match_quality)]),
+      usable = report_exists & denial_exists & !denial_claimed & !report_already_matched)
+
+  unusable = checked %>% dplyr::filter(!usable, !report_already_matched)
+  if (nrow(unusable) > 0) {
     warning(
       stringr::str_c(
-        dplyr::n_distinct(approved_duplicates$disaster_number),
-        " disaster number(s) map to more than one approved PDA report and are ",
-        "likely incorrect: ",
+        nrow(unusable), " hand-checked PDA-to-denial link(s) could not be ",
+        "applied and should be reviewed: ",
         stringr::str_c(
-          sort(unique(approved_duplicates$disaster_number)), collapse = ", ")),
+          unusable$pda_file, " -> ", unusable$denial_id, " (",
+          dplyr::case_when(
+            !unusable$report_exists ~ "no such report in the archive",
+            !unusable$denial_exists ~ "FEMA no longer publishes this denial",
+            unusable$denial_claimed ~ "another report already matched this denial",
+            TRUE ~ "unknown reason"),
+          ")",
+          collapse = "; ")),
       call. = FALSE) }
 
-  invisible(pda_df)
+  applied = checked %>%
+    dplyr::filter(usable) %>%
+    dplyr::select(pda_file, linked_denial_id = denial_id)
+
+  if (nrow(applied) == 0) { return(denied_pdas) }
+
+  denied_pdas %>%
+    dplyr::mutate(pda_file = basename(path)) %>%
+    dplyr::left_join(applied, by = "pda_file", relationship = "many-to-one") %>%
+    dplyr::mutate(
+      match_quality = dplyr::if_else(
+        is.na(match_quality) & !is.na(linked_denial_id),
+        "manual: linked by hand, because two of the state's requests were decided on the same day and FEMA's record names neither in a way a rule could tie to its report",
+        match_quality),
+      denial_id = dplyr::coalesce(denial_id, linked_denial_id)) %>%
+    dplyr::select(-pda_file, -linked_denial_id)
+}
+
+#' Add the measures derived from a PDA report alone
+#'
+#' The decision, the combined cost estimate, and the per capita threshold ratio
+#' are read from the report and nothing else, so they belong to every PDA record
+#' whether or not it is later joined to FEMA's declaration and denial records.
+#' They are computed here, outside `join_pda_outcomes()`, so that the
+#' `join_outcomes = FALSE` path returns them too.
+
+#' @param pda_df A dataframe of extracted PDA records.
+#' @return `pda_df` with `decision`, `cost_estimate_ia_pa_total`, and
+#'   `pa_threshold_ratio` added.
+#' @noRd
+add_pda_summary_measures = function(pda_df) {
+  pda_df %>%
+    dplyr::mutate(
+      decision = dplyr::case_when(
+        stringr::str_detect(event_type, "denial") ~ "Denied",
+        stringr::str_detect(event_type, "approv") ~ "Approved"),
+      ## a single estimate of the damage across both assistance programs; zero
+      ## where neither program reported a cost
+      cost_estimate_ia_pa_total = rowSums(
+        cbind(pa_cost_estimate_total, ia_cost_estimate_total), na.rm = TRUE),
+      pa_threshold_ratio =
+        pa_per_capita_impact_statewide / pa_per_capita_impact_indicator_statewide)
+}
+
+#' Join PDA attributes onto FEMA's own record of what was declared and denied
+#'
+#' The PDA reports are text extracted from PDFs and are not a complete or
+#' authoritative list of requests: a report can be missing, and a report that is
+#' present can name a state or a disaster number the text was misread from.
+#' FEMA's `DisasterDeclarationsSummaries` (granted major disaster declarations)
+#' and `DeclarationDenials` (turned-down requests) are authoritative, so those
+#' two records together define the universe of rows returned here, and the PDA
+#' attributes are attached to them. A request with no usable PDA report keeps
+#' its row, with the PDA columns empty.
+#'
+#' Approvals and denials are matched differently because they carry different
+#' keys: an approved request shares a disaster number with the declarations
+#' record, whereas a denied request has no number at all and must be matched on
+#' state, decision date, and hazard type -- see
+#' `match_denied_pdas_to_denials()`.
+#'
+#' @param pda_df A dataframe of extracted PDA records, after
+#'   `add_pda_derived_columns()`.
+#' @return One row per authoritative FEMA record, with the PDA columns joined on.
+#' @noRd
+join_pda_outcomes = function(pda_df) {
+
+  declarations = rfema::open_fema(
+      data_set = "DisasterDeclarationsSummaries",
+      ## major disaster declarations only; a PDA precedes a major disaster
+      ## request, not an emergency declaration or a fire management grant
+      filters = list(declarationType = "=DR"),
+      ask_before_call = FALSE) %>%
+    janitor::clean_names() %>%
+    ## the source returns one row per designated area, usually a county, so a
+    ## single declaration appears many times
+    dplyr::distinct(fema_declaration_string, .keep_all = TRUE) %>%
+    dplyr::transmute(
+      disaster_number = as.character(disaster_number),
+      state,
+      declaration_date = lubridate::as_date(declaration_date),
+      declaration_title,
+      decision = "Approved",
+      ## FEMA's record of the programs the declaration turned on. `fema_`-named
+      ## here so the final rename pass leaves them untouched.
+      fema_ihp_declared = as.logical(ih_program_declared),
+      fema_ia_declared = as.logical(ia_program_declared),
+      fema_pa_declared = as.logical(pa_program_declared),
+      fema_hm_declared = as.logical(hm_program_declared)) %>%
+    ## the declarations record abbreviates the state; the PDA text spells it out
+    dplyr::left_join(
+      tidycensus::fips_codes %>% dplyr::distinct(state_name, state),
+      by = "state",
+      relationship = "many-to-one") %>%
+    dplyr::select(-state)
+
+  denials = rfema::open_fema(data_set = "DeclarationDenials", ask_before_call = FALSE) %>%
+    janitor::clean_names() %>%
+    dplyr::filter(
+      ## FEMA has published this status as both "denial" and "Turndown"; both
+      ## name the same outcome, a request the President declined
+      stringr::str_to_lower(current_request_status) %in% c("denial", "turndown"),
+      declaration_request_type == "Major Disaster") %>%
+    dplyr::transmute(
+      state_name = stringr::str_trim(state),
+      declaration_request_date = lubridate::as_date(declaration_request_date),
+      request_status_date = lubridate::as_date(request_status_date),
+      declaration_title = stringr::str_trim(incident_name),
+      requested_incident_types = stringr::str_trim(requested_incident_types),
+      decision = "Denied",
+      ## FEMA's record of the programs the request asked for. Requests for the
+      ## Individual Assistance umbrella are recorded under `ihProgramRequested`
+      ## (the Individuals and Households Program replaced the older Individual
+      ## Assistance program in 2002; `iaProgramRequested` is FALSE throughout
+      ## the years the PDA archive covers).
+      fema_ihp_requested = as.logical(ih_program_requested),
+      fema_ia_requested = as.logical(ia_program_requested),
+      fema_pa_requested = as.logical(pa_program_requested),
+      fema_hm_requested = as.logical(hm_program_requested)) %>%
+    dplyr::mutate(
+      denial_hazards = extract_hazard_categories(stringr::str_c(
+        dplyr::coalesce(declaration_title, ""),
+        dplyr::coalesce(requested_incident_types, ""),
+        sep = " ")),
+      ## the record has no disaster number, so this identifies a denial for the
+      ## match and makes a denial claimed by two PDAs detectable
+      denial_id = stringr::str_c(
+        state_name, request_status_date,
+        dplyr::coalesce(declaration_title, "unnamed"),
+        sep = " | ")) %>%
+    ## FEMA publishes a small number of denials twice, as rows identical in
+    ## every field (one West Virginia request as of this writing). Keeping both
+    ## would return two universe rows for one request and attach the same PDA
+    ## report to each of them.
+    dplyr::distinct(denial_id, .keep_all = TRUE)
+
+  ## `decision`, `cost_estimate_ia_pa_total` and `pa_threshold_ratio` arrive
+  ## already computed, from `add_pda_summary_measures()`, so that the
+  ## `join_outcomes = FALSE` path carries them too
+  pdas = pda_df %>%
+    dplyr::mutate(disaster_number = as.character(disaster_number)) %>%
+    ## a report whose decision could not be read cannot be matched to an
+    ## authoritative record
+    dplyr::filter(!is.na(decision))
+
+  ## an approved request may have more than one report (an original and an
+  ## appeal) but only one declaration, so the most recent report is kept and the
+  ## fact that others exist is recorded in the match description
+  pdas_approved_all = pdas %>%
+    dplyr::filter(decision == "Approved", !is.na(disaster_number))
+
+  pdas_approved = pdas_approved_all %>%
+    dplyr::arrange(dplyr::desc(event_date_determined)) %>%
+    dplyr::add_count(disaster_number, name = "report_count") %>%
+    dplyr::slice_head(n = 1, by = disaster_number) %>%
+    dplyr::mutate(
+      match_quality = dplyr::if_else(
+        report_count > 1,
+        stringr::str_c(
+          "exact: joined on the disaster number, but ", report_count,
+          " PDA reports exist for this declaration and the most recent was kept"),
+        "exact: joined on the disaster number")) %>%
+    dplyr::select(-report_count)
+
+  ## reports deliberately set aside by the dedup above, so the message below can
+  ## keep them apart from reports that genuinely failed to match
+  superseded_paths = setdiff(pdas_approved_all$path, pdas_approved$path)
+
+  ## reports whose state could not be read -- a tribal report names the tribe,
+  ## not a state -- are kept: the state-keyed passes cannot reach them, but the
+  ## date-only pass and the hand-checked links can
+  pdas_denied = pdas %>%
+    dplyr::filter(decision == "Denied") %>%
+    match_denied_pdas_to_denials(denials)
+
+  joined_approved = declarations %>%
+    tidylog::left_join(
+      ## FEMA's own state name is authoritative, so the report's text-derived
+      ## copy is dropped rather than returned alongside it
+      pdas_approved %>% dplyr::select(-state_name),
+      ## the disaster number is unique nationally, so it alone identifies the
+      ## declaration. The state is deliberately not part of the key: a tribal
+      ## report names no state, and one whose state was misread would otherwise
+      ## be dropped rather than matched.
+      by = c("disaster_number", "decision"),
+      relationship = "many-to-one")
+
+  joined_denied = denials %>%
+    tidylog::left_join(
+      pdas_denied %>%
+        dplyr::filter(!is.na(denial_id)) %>%
+        dplyr::select(-state_name, -decision, -disaster_number),
+      by = "denial_id",
+      relationship = "many-to-one") %>%
+    dplyr::select(-denial_id) %>%
+    ## FEMA's own date the request was turned down: the counterpart of
+    ## `declaration_date` for a denied request, and the field every denial match
+    ## is keyed on. 
+    dplyr::rename(denial_date = request_status_date)
+
+  outcomes = dplyr::bind_rows(joined_approved, joined_denied) %>%
+    dplyr::mutate(pda_matched = !is.na(path))
+
+  ## Counted by source file rather than by subtracting matched rows from the
+  ## report total. A declaration with both an original and an appeal report keeps
+  ## only the most recent, and the one set aside is represented in the data by
+  ## its sibling.
+  matched_paths = stats::na.omit(outcomes$path)
+
+  ## A report set aside by the dedup counts as represented only if the
+  ## declaration it describes was itself matched -- by its sibling report.
+  superseded_represented = pdas_approved_all$path[
+    pdas_approved_all$path %in% superseded_paths &
+      pdas_approved_all$disaster_number %in% outcomes$disaster_number[outcomes$pda_matched]]
+
+  ## Reports set aside as an original superseded by its appeal are not match
+  ## failures -- the declaration they belong to is present, described by its
+  ## most recent report -- so they are excluded from the unmatched count that
+  ## `get_preliminary_damage_assessments()` reports.
+  unmatched_reports = setdiff(pda_df$path, c(matched_paths, superseded_represented))
+
+  ## Every returned column is labelled by where its value came from: `fema_`
+  ## for FEMA's own declaration and denial records, `pda_` for values read out
+  ## of the PDF reports. The two decision dates are one fact -- the day FEMA
+  ## settled the request -- recorded in different source datasets, so they are
+  ## combined into a single column.
+  joined = outcomes %>%
+    dplyr::select(-dplyr::any_of("disaster_number_filename")) %>%
+    dplyr::mutate(
+      fema_decision_date = dplyr::coalesce(declaration_date, denial_date),
+      fema_decision_year = lubridate::year(fema_decision_date)) %>%
+    dplyr::select(-declaration_date, -denial_date) %>%
+    dplyr::rename(
+      fema_disaster_number = disaster_number,
+      fema_state_name = state_name,
+      fema_decision = decision,
+      fema_declaration_request_date = declaration_request_date,
+      fema_declaration_title = declaration_title,
+      fema_requested_incident_types = requested_incident_types,
+      fema_hazards = denial_hazards,
+      pda_match_quality = match_quality) %>%
+    ## output names for the report-side columns; `declaration_title` and
+    ## `decision` are free again, their FEMA-side owners renamed just above
+    dplyr::rename(
+      tribal_flag = event_native_flag,
+      declaration_title = event_title,
+      decision = event_type,
+      date_determined = event_date_determined) %>%
+    dplyr::select(
+      -dplyr::any_of("pa_per_capita_impact_indicator_statewide_source")) %>%
+    dplyr::rename_with(
+      ~ stringr::str_c("pda_", .x),
+      .cols = !dplyr::starts_with(c("fema_", "pda_"))) %>%
+    dplyr::select(
+      fema_disaster_number, fema_state_name, fema_decision, fema_decision_date,
+      fema_decision_year, fema_declaration_request_date, fema_declaration_title,
+      fema_requested_incident_types, fema_hazards,
+      fema_ihp_declared, fema_ia_declared, fema_pa_declared, fema_hm_declared,
+      fema_ihp_requested, fema_ia_requested, fema_pa_requested,
+      fema_hm_requested, pda_matched,
+      pda_match_quality, dplyr::any_of("pda_warnings"), dplyr::everything())
+
+  ## the count feeds the single consolidated warning
+  ## `get_preliminary_damage_assessments()` emits
+  attr(joined, "n_unmatched") = length(unmatched_reports)
+  joined
 }
 
-#' Get Data from Preliminary Damage Assessments Submitted to FEMA for Disaster Declarations
+#' Get FEMA Preliminary Damage Assessments Report Data
 #'
 #' @description Retrieves data extracted from PDF preliminary damage assessment (PDA)
-#'   reports submitted to FEMA for disaster declarations.
+#'   reports published by FEMA as part of the disaster declaration request process.
 #'
 #' @details Data are extracted from PDF reports hosted at
 #'   \url{https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports}.
 #'   Owing to the unstructured nature of the source documents, some fields may be incorrect
 #'   in the data returned by the function, though significant quality checks have been
 #'   implemented in an effort to produce a high-quality dataset.
+#' 
+#'   With `join_outcomes = TRUE` (the default), the PDA data are attached to
+#'   FEMA's own structured records of which declaration requests were declared and
+#'   denied. FEMA's
+#'   `DisasterDeclarationsSummaries` (granted major disaster declarations) and
+#'   `DeclarationDenials` (turned-down major disaster requests) datasets are
+#'   authoritative, so every such record is returned, with the PDA columns empty
+#'   where no report could be matched to it. An approved request is matched on
+#'   its disaster number. A denied request never receives a disaster number, so
+#'   it is matched on state, on the decision date the report prints, and on
+#'   agreement between the hazards the two records describe, with anything
+#'   ambiguous left unmatched; `match_quality` records
+#'   which of these applied. Set `join_outcomes = FALSE` for the reports alone.
 #'
-#'   Before the data are returned -- whether newly generated or read from the cache --
-#'   they are checked for the ways that parsing an unstructured PDF fails silently:
-#'   values that are not finite numbers, negative counts, percentages outside 0-100,
-#'   cost estimates small enough to be a label's footnote number rather than a total,
-#'   demographic shares of exactly zero (the signature of a blank field whose footnote
-#'   number was read as the value),
-#'   statutory per capita thresholds outside their published range, damage categories
-#'   summing to more than the stated total of impacted residences, values recorded for
-#'   a program the report says was not requested, values far above the rest of their
-#'   column, malformed or missing disaster numbers, implausible determination dates,
-#'   and columns that are almost entirely empty among the reports that should state
-#'   them. Anything found is raised as a single `warning()` naming example source
-#'   reports; the values themselves are returned as parsed, so each can be checked
-#'   against its PDF. The share of each field that is missing among the reports that
-#'   requested the program and were approved is reported with `message()`, since
-#'   whether a given rate is a problem is a judgment rather than a rule.
+#'   Data quality is reported through a single consolidated warning: how many
+#'   records carry values that may be incorrect -- each such record's specific
+#'   issue(s) are written to the `pda_warnings` column -- and how many PDA
+#'   reports could not be matched to an authoritative FEMA declaration or
+#'   denial and are therefore absent from the returned data.
 #'
 #' @param file_path The file path to the cached dataset, or if there is no cache, the path
 #'   at which to cache the resulting data.
@@ -1394,60 +2144,157 @@ warn_approved_disaster_number_duplicates = function(pda_df) {
 #'   download them and to refresh the archive as FEMA publishes new reports.
 #' @param use_cache Boolean. Read the existing dataset stored at `file_path`? If FALSE,
 #'   data will be generated anew. Else, if a file exists at `file_path`, this file will be returned.
+#' @param join_outcomes Boolean. Return FEMA's authoritative record of every
+#'   granted and denied major disaster request, with the PDA attributes joined
+#'   onto it? If FALSE, one row per PDA report is
+#'   returned instead, without the declaration and denial columns.
 #'
-#' @return A dataframe of preliminary damage assessment reports. Columns include:
+#' @return A dataframe with one row per FEMA declaration or denial record
+#'   (or, when `join_outcomes = FALSE`, one row per PDA report). Several fields
+#'   have no labelled equivalent in the source documents and are derived from
+#'   the report text; the logic used is given with each.
+#'
+#'   When `join_outcomes = TRUE`, every column name carries a prefix saying
+#'   where its value came from: `fema_` for FEMA's own declaration and denial
+#'   records, `pda_` for values read out of the PDF reports. The column names
+#'   listed below are the prefixed ones. When `join_outcomes = FALSE` the
+#'   columns are returned unprefixed (so `pda_hazards` below is `hazards`, and
+#'   `pda_decision` is `decision`), and
+#'   the columns describing the FEMA record or the match to it --
+#'   `fema_decision_date`, `fema_decision_year`, `fema_declaration_request_date`,
+#'   `fema_declaration_title`, `fema_requested_incident_types`, `fema_hazards`,
+#'   the eight `fema_*_declared`/`fema_*_requested` program fields,
+#'   `pda_matched`, and `pda_match_quality` -- are absent.
+#'   Columns include:
 #'   \describe{
-#'     \item{path}{The local file path to the source PDA PDF.}
-#'     \item{disaster_number}{FEMA disaster number.}
-#'     \item{event_type}{Type of decision: "approved", "denial", "appeal_approved", or
-#'        "appeal_denial". The denial classes are read from FEMA's filename convention and the
-#'        report title. "appeal_approved" is read from the report body instead, because an
-#'        approved appeal is titled and named exactly like a first-instance approval and carries
-#'        a disaster number; what identifies it is a narrative of a denied request that was
-#'        subsequently appealed. Both halves of that narrative are required, so ordinary
-#'        approvals that merely describe the appeals process are not misclassified.}
-#'     \item{event_title}{Title/description of the disaster event.}
-#'     \item{event_date_determined}{Date the PDA determination was made.}
-#'     \item{event_native_flag}{1 if tribal request, 0 otherwise.}
-#'     \item{pa_requested}{1 if Public Assistance was requested, 0 otherwise.}
-#'     \item{pa_preemptive_declaration}{1 if the joint PDA requirement was waived due to the severity of the event, 0 otherwise.}
-#'     \item{pa_primary_impact}{The primary type of impact described for Public Assistance purposes.}
-#'     \item{pa_cost_estimate_total}{Estimated total Public Assistance cost.}
-#'     \item{pa_per_capita_impact_statewide}{Statewide (or territory/commonwealth) per capita impact amount.}
-#'     \item{pa_per_capita_impact_indicator_statewide}{FEMA's statutory statewide per capita
-#'        *threshold* in dollars for the relevant year (observed range 1.24--1.94), not a ratio
-#'        and not a "Met"/"Not Met" categorical despite the field's FEMA-assigned name. Compare
-#'        it against `pa_per_capita_impact_statewide`, which is the estimated per capita impact
-#'        in the same units; the ratio of the two is what indicates whether the threshold was met.}
-#'     \item{pa_per_capita_impact_countywide}{Raw text of countywide per capita impact ratios (may list
+#'     \item{fema_disaster_number}{FEMA disaster number. NA for a denied request, which is never assigned one.}
+#'     \item{fema_state_name}{The requesting state, territory, or the District of Columbia.
+#'        For a joined record this is FEMA's own value; on the PDA side it is the first
+#'        state or territory name appearing anywhere in the report text, since FEMA does
+#'        not print it as a labelled field.}
+#'     \item{fema_decision}{"Approved" or "Denied".}
+#'     \item{fema_decision_date}{The date FEMA settled the request: the date the major
+#'        disaster declaration was granted for an approved request, and FEMA's own
+#'        `request_status_date` -- the date the request was turned down -- for a denied one.}
+#'     \item{fema_decision_year}{The calendar year of `fema_decision_date`.}
+#'     \item{fema_declaration_request_date}{Date the state filed the request (denied records only).}
+#'     \item{fema_declaration_title}{FEMA's name for the event.}
+#'     \item{fema_requested_incident_types}{FEMA's own classification of the requested incident
+#'        types (denied records only).}
+#'     \item{fema_hazards}{Semicolon-separated hazard categories read from FEMA's
+#'        `fema_declaration_title` and `fema_requested_incident_types`, on the same category set
+#'        as `pda_hazards` so the two can be compared (denied records only).}
+#'     \item{fema_ihp_declared, fema_ia_declared, fema_pa_declared, fema_hm_declared}{FEMA's
+#'        record of whether the declaration turned on the Individuals and Households Program,
+#'        the (pre-2002) Individual Assistance program, Public Assistance, and Hazard
+#'        Mitigation (approved records only; NA for denied ones). A program can be declared
+#'        without appearing in the PDA -- added by a later request -- and requested without
+#'        being declared, so these legitimately diverge from the `pda_*_requested` flags.}
+#'     \item{fema_ihp_requested, fema_ia_requested, fema_pa_requested, fema_hm_requested}{FEMA's
+#'        record of the programs the denied request asked for (denied records only; NA for
+#'        approved ones). Requests for the Individual Assistance umbrella are recorded under
+#'        `fema_ihp_requested`; `fema_ia_requested` names the pre-2002 Individual Assistance
+#'        program and is FALSE throughout the years the PDA archive covers. `fema_ihp_requested`
+#'        is narrower than `pda_ia_requested`: a request only for a component program such as
+#'        Disaster Unemployment Assistance sets the `pda_` flag but not FEMA's.}
+#'     \item{pda_matched}{TRUE where a PDA report was matched to this FEMA record.}
+#'     \item{pda_warnings}{Semicolon-separated descriptions of the data quality problems
+#'        found on this record -- a value that cannot be what its field measures, a
+#'        footnote number standing in for a dollar total, damage categories that do not
+#'        add up, a report contradicting itself about whether a program was requested,
+#'        and the like. NA where no problem was found. Values are returned as parsed, so
+#'        each problem can be checked against its source report. Named `warnings` when
+#'        `join_outcomes = FALSE`.}
+#'     \item{pda_match_quality}{How the match was made, or NA where none was. "exact" covers an
+#'        approved request joined on its disaster number; a denied request whose determination
+#'        date is the denial decision date within the same state; and a denied request whose
+#'        report names no state -- a tribal report names the tribe instead -- matched on the
+#'        determination date alone, where exactly one denial in the country shares that date
+#'        and it agrees with the report on hazard or shares a word with its title.
+#'        "approximate" is a denied request matched instead to the nearest denial of the same
+#'        hazard type within seven days either side of the date the report prints, and says how
+#'        many days apart the two records are. "manual" is a link established by hand,
+#'        for the case no rule can settle: two of a state's requests decided on the same day,
+#'        with FEMA naming neither in a way that ties it to its report.}
+#'     \item{pda_path}{The local file path to the source PDA PDF.}
+#'     \item{pda_decision}{Type of decision the report announces: "approved", "denial",
+#'        "appeal_approved", or "appeal_denial". Finer-grained than `fema_decision`, which
+#'        does not distinguish an original decision from one made on appeal.}
+#'     \item{pda_declaration_title}{The report's description of the event.}
+#'     \item{pda_date_determined}{Date the PDA determination was made.}
+#'     \item{pda_tribal_flag}{1 where the request came from a tribal government, 0 otherwise.
+#'        Set where the report title contains any of "Native", "Tribe", "Tribes", "Tribal",
+#'        "Indians", "Nation", "Band", "Pueblo", "Rancheria", "Reservation", "Village",
+#'        "Traditional Council", or "IRA Council". This drives the extraction logic for many fields
+#'        because tribal records are formatted differently than state/territorial records.}
+#'     \item{pda_hazards}{Semicolon-separated hazard categories ("flooding; landslide") read from
+#'        `pda_declaration_title`. NA where no keyword matched.}
+#'     \item{pda_pa_requested}{1 where Public Assistance was requested, 0 where the report states
+#'        "Public Assistance - Not requested". Where a report says the program was not
+#'        requested but reports values for it anyway, or states no values while its narrative
+#'        does not name the program, the flag is settled from the report's opening narrative
+#'        -- see `requested_from_narrative`.}
+#'     \item{pda_pa_preemptive_declaration}{1 where the report states that the "requirement for a
+#'        joint PDA may be waived", meaning the event was severe enough that FEMA proceeded
+#'        without conducting a joint preliminary damage assessment first; 0 otherwise.}
+#'     \item{pda_pa_primary_impact}{The primary type of impact described for Public Assistance
+#'        purposes.}
+#'     \item{pda_pa_cost_estimate_total}{Estimated total Public Assistance cost.}
+#'     \item{pda_pa_per_capita_impact_statewide}{Statewide (or territory/commonwealth) per capita
+#'        impact amount.}
+#'     \item{pda_pa_per_capita_impact_indicator_statewide}{FEMA's statutory statewide per capita
+#'        *threshold* in dollars for the relevant year (observed range 1.24--1.94). A report
+#'        that states no value, or states one outside the published range, is given the value
+#'        the other reports of its fiscal year state; the indicator is uniform within a fiscal
+#'        year, so this fill is very low risk.}
+#'     \item{pda_pa_per_capita_impact_countywide}{Raw text of countywide per capita impact ratios (may list
 #'        multiple values across affected counties for a multi-county event).}
-#'     \item{pa_per_capita_impact_indicator_countywide}{FEMA's statutory countywide per capita
-#'        threshold in dollars (observed range 3.11--4.60), on the same basis as the statewide
-#'        indicator above.}
-#'     \item{pa_per_capita_impact_countywide_max}{Maximum countywide per capita impact ratio parsed
+#'     \item{pda_pa_per_capita_impact_indicator_countywide}{FEMA's statutory countywide per capita
+#'        threshold in dollars, on the same basis as the statewide indicator above.}
+#'     \item{pda_pa_per_capita_impact_countywide_max}{Maximum countywide per capita impact ratio parsed
 #'        from `pa_per_capita_impact_countywide`.}
-#'     \item{pa_per_capita_impact_countywide_min}{Minimum countywide per capita impact ratio parsed
+#'     \item{pda_pa_per_capita_impact_countywide_min}{Minimum countywide per capita impact ratio parsed
 #'        from `pa_per_capita_impact_countywide`.}
-#'     \item{ia_requested}{1 if Individual Assistance was requested, 0 otherwise.}
-#'     \item{ia_residences_impacted}{Total residences impacted.}
-#'     \item{ia_residences_destroyed}{Number of residences destroyed.}
-#'     \item{ia_residences_major_damage}{Number of residences with major damage.}
-#'     \item{ia_residences_minor_damage}{Number of residences with minor damage.}
-#'     \item{ia_residences_affected}{Number of residences affected (lowest damage category).}
-#'     \item{ia_residences_insured_total_percent}{Percentage of impacted residences with any insurance coverage.}
-#'     \item{ia_residences_insured_flood_percent}{Percentage of impacted residences with flood insurance coverage.}
-#'     \item{ia_households_poverty_percent}{Percentage of households in poverty (or low income,
+#'     \item{pda_pa_threshold_ratio}{`pa_per_capita_impact_statewide` divided by
+#'        `pa_per_capita_impact_indicator_statewide`: the estimated per capita damage expressed as
+#'        a multiple of the statutory threshold, so a value above 1 means the threshold was
+#'        exceeded.}
+#'     \item{pda_ia_requested}{1 where Individual Assistance was requested, 0 where the report states
+#'        "Individual Assistance - Not requested". Where a report states no Individual
+#'        Assistance values and its opening narrative does not name the program among those
+#'        requested, the flag is set to 0 -- see `requested_from_narrative`. Individual
+#'        Assistance is read broadly: a request only for one of its component programs
+#'        (Crisis Counseling, Disaster Unemployment Assistance, Disaster Legal Services,
+#'        Disaster Case Management) counts, so this flag can be 1 where FEMA's own
+#'        `fema_ihp_requested` is FALSE.}
+#'     \item{pda_requested_from_narrative}{Names the program whose requested flag was settled from
+#'        the report's opening narrative ("ia", "pa", or "ia; pa"), NA otherwise. The narrative is
+#'        consulted only where the report disagrees with itself: the summary says a program
+#'        was not requested while the report prints values for it, or the report prints no
+#'        values while the narrative does not name the program. A narrative naming any
+#'        component program of Individual Assistance counts as requesting Individual
+#'        Assistance.}
+#'     \item{pda_ia_residences_impacted}{Total residences impacted.}
+#'     \item{pda_ia_residences_destroyed}{Number of residences destroyed.}
+#'     \item{pda_ia_residences_major_damage}{Number of residences with major damage.}
+#'     \item{pda_ia_residences_minor_damage}{Number of residences with minor damage.}
+#'     \item{pda_ia_residences_affected}{Number of residences affected (lowest damage category).}
+#'     \item{pda_ia_residences_insured_total_percent}{Percentage of impacted residences with any insurance coverage.}
+#'     \item{pda_ia_residences_insured_flood_percent}{Percentage of impacted residences with flood insurance coverage.}
+#'     \item{pda_ia_households_poverty_percent}{Percentage of households in poverty (or low income,
 #'        depending on report vintage).}
-#'     \item{ia_households_owner_percent}{Percentage of households that are owner-occupied.}
-#'     \item{ia_population_other_government_assistance_percent}{Percentage of the population receiving
+#'     \item{pda_ia_households_owner_percent}{Percentage of households that are owner-occupied.}
+#'     \item{pda_ia_population_other_government_assistance_percent}{Percentage of the population receiving
 #'        other government assistance (e.g. SSI, SNAP).}
-#'     \item{ia_pre_disaster_unemployment_percent}{Pre-disaster unemployment rate.}
-#'     \item{ia_65plus_percent}{Percentage of the population age 65 and older.}
-#'     \item{ia_18below_percent}{Percentage of the population age 18 and under.}
-#'     \item{ia_disability_percent}{Percentage of the population with a disability.}
-#'     \item{ia_ihp_cost_to_capacity_ratio}{Individuals and Households Program (IHP) Cost to Capacity (ICC) ratio.}
-#'     \item{ia_cost_estimate_total}{Estimated total Individual Assistance cost.}
-#'     \item{text}{The cleaned text extracted from the PDA PDF used to derive the fields above.}
+#'     \item{pda_ia_pre_disaster_unemployment_percent}{Pre-disaster unemployment rate.}
+#'     \item{pda_ia_65plus_percent}{Percentage of the population age 65 and older.}
+#'     \item{pda_ia_18below_percent}{Percentage of the population age 18 and under.}
+#'     \item{pda_ia_disability_percent}{Percentage of the population with a disability.}
+#'     \item{pda_ia_ihp_cost_to_capacity_ratio}{Individuals and Households Program (IHP) Cost to Capacity (ICC) ratio.}
+#'     \item{pda_ia_cost_estimate_total}{Estimated total Individual Assistance cost.}
+#'     \item{pda_cost_estimate_ia_pa_total}{`pa_cost_estimate_total` plus `ia_cost_estimate_total`,
+#'        treating a missing program cost as zero; 0 where neither program reported one.}
+#'     \item{pda_text}{The cleaned text extracted from the PDA PDF used to derive the fields above.}
 #'   }
 #' @export
 #'
@@ -1458,17 +2305,69 @@ warn_approved_disaster_number_duplicates = function(pda_df) {
 get_preliminary_damage_assessments = function(
     file_path = file.path(get_box_path(), "hazards", "urban", "preliminary-damage-assessments", "pda_data.csv"),
     directory_path = file.path(get_box_path(), "hazards", "urban", "preliminary-damage-assessments"),
-    use_cache = TRUE) {
+    use_cache = TRUE,
+    join_outcomes = TRUE) {
+
+  finalize = function(pda_df) {
+    pda_df1 = pda_df %>%
+      add_pda_derived_columns() %>%
+      impute_statewide_indicator() %>%
+      ## derived from the report alone, so they belong on both paths; this must
+      ## follow the imputation, which supplies the threshold ratio's denominator
+      add_pda_summary_measures()
+    if (join_outcomes == FALSE) {
+      ## the report-only path carries the same output names as the joined
+      ## path's pda_-prefixed equivalents. The derived Approved/Denied
+      ## `decision` -- computed for the join's benefit -- gives its name up to
+      ## the report's own decision type.
+      return(
+        pda_df1 %>%
+          dplyr::select(-dplyr::any_of(c(
+            "decision", "pa_per_capita_impact_indicator_statewide_source"))) %>%
+          dplyr::rename(
+            tribal_flag = event_native_flag,
+            declaration_title = event_title,
+            decision = event_type,
+            date_determined = event_date_determined)) }
+    join_pda_outcomes(pda_df1) }
+
+  ## The one place this function talks to the user about data quality: a single
+  ## warning covering the per-record problems (detailed in the warnings column)
+  ## and, when the FEMA records were joined, the reports no authoritative
+  ## record could be matched to.
+  report_quality = function(result, dataset_issues) {
+    warnings_column = if ("pda_warnings" %in% names(result)) {
+      "pda_warnings" } else { "warnings" }
+    n_flagged = sum(!is.na(result[[warnings_column]]))
+    n_unmatched = attr(result, "n_unmatched")
+
+    parts = character(0)
+    if (n_flagged > 0) {
+      parts = c(parts, stringr::str_c(
+        n_flagged, " record(s) have values parsed from their PDA reports ",
+        "that may be incorrect, due either to the parsing or to errors in ",
+        "the source document; the `", warnings_column, "` column describes ",
+        "each record's issue(s).")) }
+    if (!is.null(n_unmatched) && n_unmatched > 0) {
+      parts = c(parts, stringr::str_c(
+        n_unmatched, " PDA report(s) could not be matched to an ",
+        "authoritative FEMA declaration or denial; unmatched reports are ",
+        "not included in the returned data.")) }
+    if (length(dataset_issues) > 0) {
+      parts = c(parts, stringr::str_c(
+        "Dataset-wide: ", stringr::str_c(dataset_issues, collapse = " "))) }
+
+    if (length(parts) > 0) {
+      warning(stringr::str_c(parts, collapse = " "), call. = FALSE) }
+
+    attr(result, "n_unmatched") = NULL
+    result }
 
   if (!file.exists(file_path) | use_cache == FALSE) {
     if (!is.null(directory_path)) {
       file_paths = list.files(directory_path, recursive = TRUE, full.names = TRUE) %>%
-        purrr::keep(~ stringr::str_detect(.x, "pdf$"))
+        purrr::keep(~ stringr::str_detect(.x, stringr::regex("pdf$", ignore_case = TRUE)))
 
-      ## isolate per-file parsing failures (rather than letting one bad PDF abort the
-      ## entire regeneration) and surface a summary of any parsing warnings, rather than
-      ## blanket-suppressing them across the whole batch (which previously hid, among
-      ## other things, the -Inf/Inf sentinel bug fixed in extract_pda_attributes())
       safe_extract = purrr::possibly(purrr::quietly(extract_pda_attributes), otherwise = NULL)
       extraction_results = purrr::map(file_paths, safe_extract)
 
@@ -1488,53 +2387,77 @@ get_preliminary_damage_assessments = function(
 
       pda_df1 = successful_results %>% purrr::map_dfr(~ .x$result)
 
-      ## Correct disaster numbers duplicated across genuinely different reports (a
-      ## typo'd or missing number colliding two disasters into one), then flag any
-      ## approved-report collisions that could not be resolved from the text.
       pda_df2 = pda_df1 %>%
         correct_duplicate_disaster_numbers() %>%
         drop_impossible_percentages() %>%
         dplyr::mutate(parser_version = pda_parser_version())
 
-      warn_approved_disaster_number_duplicates(pda_df2)
-      check_pda_quality(pda_df2)
+      pda_df3 = resolve_requested_flags(pda_df2)
+      pda_df4 = check_pda_quality(pda_df3)
 
       readr::write_csv(pda_df2, file_path)
 
-      return(pda_df2)
+      return(report_quality(
+        finalize(pda_df4), attr(pda_df4, "dataset_issues")))
     } }
 
-  if (use_cache == TRUE) {
+  if (use_cache == TRUE && file.exists(file_path)) {
     message("Reading cached preliminary damage assessment data from disk.")
     check_cache_parser_version(file_path)
-    ## self-heal caches written before the duplicate-correction logic existed, and
-    ## surface any approved-report collisions that remain
-    pda_df = readr::read_csv(file_path) %>% correct_duplicate_disaster_numbers()
-    warn_approved_disaster_number_duplicates(pda_df)
-    ## also run on the cached path: a cache written by older parsing logic can
-    ## carry problems the current code no longer produces, and reading it must
-    ## not present them as clean
-    check_pda_quality(pda_df)
-    return(pda_df)
+
+    pda_df = readr::read_csv(file_path, show_col_types = FALSE) %>%
+      correct_duplicate_disaster_numbers() %>%
+      resolve_requested_flags() %>%
+      check_pda_quality()
+
+    return(report_quality(
+      finalize(pda_df), attr(pda_df, "dataset_issues")))
   }
 
-  stop("Unable to generate preliminary damage assessment data; ensure specified file and/or directory paths are valid.")
+  stop(
+    stringr::str_c(
+      "Unable to generate preliminary damage assessment data. No cached dataset ",
+      "exists at `file_path` (", file_path, ") and no `directory_path` of PDA ",
+      "PDFs was given to parse. Run scrape_pda_pdfs() to populate a directory, ",
+      "or point `file_path` at an existing cache."),
+    call. = FALSE)
 }
 
 utils::globalVariables(c(
-  "event_title_pda", "pa_per_capita_impact_indicator_statewide_pda", "pa_per_capita_impact_statewide_pda" ,
-  "pa_program_declared_openfema", "pci", "pci_threshold_current",
-  "project_amount_federal_share_no_administrative_costs",
-  "project_amount_total_no_administrative_costs", "public_assistance",
-  "text_pda", "tribal_request_openfema", "federal_cost_share_rate", "funding_lost_flag_any",
-  "funding_lost_flag_cost_share", "funding_lost_flag_pci", "funding_lost_flag_pci_snowstorm",
-  "funding_lost_flag_snowstorm", "date_match_string", "declaration_date_openfema",
-  "disaster_number_count", "event_date_determined", "event_native_flag", "event_title",
-  "disaster_number", "disaster_number_from_text", "approved_count", "event_type", "text",
+  "date_match_string", "disaster_number_count", "event_date_determined",
+  "event_native_flag", "event_title", "disaster_number",
+  "disaster_number_from_text", "approved_count", "event_type", "text",
   "first_date_match_string", "disaster_number_filename", "parser_version",
-  "uses_tribal_layout", "filename_lower",
-  "ia_cost_estimate_total", "ia_residences_insured_total_percent",
-  "pa_per_capita_impact_countywide", "pa_per_capita_impact_countywide_1",
-  "pa_per_capita_impact_indicator_countywide", "pa_per_capita_impact_indicator_statewide",
-  "pa_primary_impact", "base_name", "base_name_count", "needs_hash", "destination_file",
-  "status", "share_missing"))
+  "uses_tribal_layout", "filename_lower", "ia_cost_estimate_total",
+  "ia_residences_insured_total_percent", "pa_per_capita_impact_countywide",
+  "pa_per_capita_impact_countywide_1",
+  "pa_per_capita_impact_indicator_countywide",
+  "pa_per_capita_impact_indicator_statewide", "pa_primary_impact",
+  "base_name", "base_name_count", "needs_hash", "destination_file", "status",
+  "share_missing", "state_name", "hazards", "denial_hazards", "denial_id",
+  "request_status_date", "declaration_request_date", "declaration_title",
+  "requested_incident_types", "current_request_status",
+  "declaration_request_type", "incident_name", "fema_declaration_string",
+  "declaration_date", "decision", "state", "path", "pda_id",
+  "fema_disaster_number", "fema_state_name", "fema_decision",
+  "fema_decision_date", "fema_decision_year", "fema_declaration_request_date",
+  "fema_declaration_title", "fema_requested_incident_types", "fema_hazards",
+  "pda_match_quality",
+  "candidate_count", "candidates_per_pda", "candidate_count_resolved",
+  "pdas_per_denial", "match_ok", "match_quality", "hazards_agree",
+  "shared_hazard_count", "days_from_denial", "report_count", "pda_matched",
+  "pa_cost_estimate_total", "cost_estimate_ia_pa_total",
+  "pa_threshold_ratio", "denial_date", "request_sentence", "warnings",
+  "ih_program_declared", "ia_program_declared", "pa_program_declared",
+  "hm_program_declared", "ih_program_requested", "ia_program_requested",
+  "pa_program_requested", "hm_program_requested",
+  "fema_ihp_declared", "fema_ia_declared", "fema_pa_declared",
+  "fema_hm_declared", "fema_ihp_requested", "fema_ia_requested",
+  "fema_pa_requested", "fema_hm_requested",
+  "narrative_requests_ia",
+  "narrative_requests_pa", "ia_from_narrative", "pa_from_narrative",
+  "requested_from_narrative", "fiscal_year", "fiscal_year_stated",
+  "fiscal_year_determined", "indicator_for_fiscal_year",
+  "reports_stating_value", "can_impute", "pda_file", "report_exists",
+  "denial_exists", "denial_claimed", "report_already_matched", "usable",
+  "linked_denial_id", "shares_a_word"))
diff --git a/R/get_usgs_gage.R b/R/get_usgs_gage.R
index 1430a75..063a9b8 100644
--- a/R/get_usgs_gage.R
+++ b/R/get_usgs_gage.R
@@ -157,15 +157,26 @@ get_usgs_gage = function(
   ## daily_max must be computed from the continuous ("Instantaneous") record.
   ## Each series' period-of-record start is retained: the continuous endpoint
   ## needs explicit time bounds (see below)
-  site_inventory = dataRetrieval::read_waterdata_ts_meta(
-      monitoring_location_id = site_metadata$monitoring_location_id,
-      parameter_code = parameter_code,
-      computation_identifier = dplyr::if_else(
-        statistic == "daily_mean", "Mean", "Instantaneous"),
-      computation_period_identifier = dplyr::if_else(
-        statistic == "daily_mean", "Daily", "Points"),
-      skipGeometry = TRUE) %>%
-    tibble::as_tibble() %>%
+  ## request the inventory in batches of ten sites. dataRetrieval 2.7.25 splits
+  ## long site lists into several requests itself, but if any one request
+  ## matches no series it types that batch's begin_utc/end_utc columns as
+  ## character rather than datetime and fails when combining batches ("Corrupt
+  ## POSIXct" from vctrs). Ten site IDs always fit in a single request, and
+  ## keeping only the columns used here avoids the mistyped ones
+  site_inventory = site_metadata$monitoring_location_id %>%
+    split(ceiling(seq_along(.) / 10)) %>%
+    purrr::map(
+      ~ dataRetrieval::read_waterdata_ts_meta(
+        monitoring_location_id = .x,
+        parameter_code = parameter_code,
+        computation_identifier = dplyr::if_else(
+          statistic == "daily_mean", "Mean", "Instantaneous"),
+        computation_period_identifier = dplyr::if_else(
+          statistic == "daily_mean", "Daily", "Points"),
+        skipGeometry = TRUE) %>%
+        tibble::as_tibble() %>%
+        dplyr::select(monitoring_location_id, begin)) %>%
+    purrr::list_rbind() %>%
     ## a site can have several series (e.g. sublocations); keep the earliest
     dplyr::summarize(
       record_begin_date = as.Date(min(begin, na.rm = TRUE)),
diff --git a/man/climateapi-package.Rd b/man/climateapi-package.Rd
index f5b4464..9962c11 100644
--- a/man/climateapi-package.Rd
+++ b/man/climateapi-package.Rd
@@ -20,7 +20,6 @@ Useful links:
 
 Authors:
 \itemize{
-  \item Will Curran-Groome \email{wcurrangroome@urban.org} (\href{https://orcid.org/0000-0001-6432-7561}{ORCID})
   \item Kameron Lloyd
 }
 
diff --git a/man/get_preliminary_damage_assessments.Rd b/man/get_preliminary_damage_assessments.Rd
index b6cccf0..a4f8f09 100644
--- a/man/get_preliminary_damage_assessments.Rd
+++ b/man/get_preliminary_damage_assessments.Rd
@@ -2,14 +2,15 @@
 % Please edit documentation in R/get_preliminary_damage_assessments.R
 \name{get_preliminary_damage_assessments}
 \alias{get_preliminary_damage_assessments}
-\title{Get Data from Preliminary Damage Assessments Submitted to FEMA for Disaster Declarations}
+\title{Get FEMA Preliminary Damage Assessments Report Data}
 \usage{
 get_preliminary_damage_assessments(
   file_path = file.path(get_box_path(), "hazards", "urban",
     "preliminary-damage-assessments", "pda_data.csv"),
   directory_path = file.path(get_box_path(), "hazards", "urban",
     "preliminary-damage-assessments"),
-  use_cache = TRUE
+  use_cache = TRUE,
+  join_outcomes = TRUE
 )
 }
 \arguments{
@@ -22,66 +23,164 @@ download them and to refresh the archive as FEMA publishes new reports.}
 
 \item{use_cache}{Boolean. Read the existing dataset stored at \code{file_path}? If FALSE,
 data will be generated anew. Else, if a file exists at \code{file_path}, this file will be returned.}
+
+\item{join_outcomes}{Boolean. Return FEMA's authoritative record of every
+granted and denied major disaster request, with the PDA attributes joined
+onto it? If FALSE, one row per PDA report is
+returned instead, without the declaration and denial columns.}
 }
 \value{
-A dataframe of preliminary damage assessment reports. Columns include:
+A dataframe with one row per FEMA declaration or denial record
+(or, when \code{join_outcomes = FALSE}, one row per PDA report). Several fields
+have no labelled equivalent in the source documents and are derived from
+the report text; the logic used is given with each.
+
+When \code{join_outcomes = TRUE}, every column name carries a prefix saying
+where its value came from: \code{fema_} for FEMA's own declaration and denial
+records, \code{pda_} for values read out of the PDF reports. The column names
+listed below are the prefixed ones. When \code{join_outcomes = FALSE} the
+columns are returned unprefixed (so \code{pda_hazards} below is \code{hazards}, and
+\code{pda_decision} is \code{decision}), and
+the columns describing the FEMA record or the match to it --
+\code{fema_decision_date}, \code{fema_decision_year}, \code{fema_declaration_request_date},
+\code{fema_declaration_title}, \code{fema_requested_incident_types}, \code{fema_hazards},
+the eight \verb{fema_*_declared}/\verb{fema_*_requested} program fields,
+\code{pda_matched}, and \code{pda_match_quality} -- are absent.
+Columns include:
 \describe{
-\item{path}{The local file path to the source PDA PDF.}
-\item{disaster_number}{FEMA disaster number.}
-\item{event_type}{Type of decision: "approved", "denial", "appeal_approved", or
-"appeal_denial". The denial classes are read from FEMA's filename convention and the
-report title. "appeal_approved" is read from the report body instead, because an
-approved appeal is titled and named exactly like a first-instance approval and carries
-a disaster number; what identifies it is a narrative of a denied request that was
-subsequently appealed. Both halves of that narrative are required, so ordinary
-approvals that merely describe the appeals process are not misclassified.}
-\item{event_title}{Title/description of the disaster event.}
-\item{event_date_determined}{Date the PDA determination was made.}
-\item{event_native_flag}{1 if tribal request, 0 otherwise.}
-\item{pa_requested}{1 if Public Assistance was requested, 0 otherwise.}
-\item{pa_preemptive_declaration}{1 if the joint PDA requirement was waived due to the severity of the event, 0 otherwise.}
-\item{pa_primary_impact}{The primary type of impact described for Public Assistance purposes.}
-\item{pa_cost_estimate_total}{Estimated total Public Assistance cost.}
-\item{pa_per_capita_impact_statewide}{Statewide (or territory/commonwealth) per capita impact amount.}
-\item{pa_per_capita_impact_indicator_statewide}{FEMA's statutory statewide per capita
-\emph{threshold} in dollars for the relevant year (observed range 1.24--1.94), not a ratio
-and not a "Met"/"Not Met" categorical despite the field's FEMA-assigned name. Compare
-it against \code{pa_per_capita_impact_statewide}, which is the estimated per capita impact
-in the same units; the ratio of the two is what indicates whether the threshold was met.}
-\item{pa_per_capita_impact_countywide}{Raw text of countywide per capita impact ratios (may list
+\item{fema_disaster_number}{FEMA disaster number. NA for a denied request, which is never assigned one.}
+\item{fema_state_name}{The requesting state, territory, or the District of Columbia.
+For a joined record this is FEMA's own value; on the PDA side it is the first
+state or territory name appearing anywhere in the report text, since FEMA does
+not print it as a labelled field.}
+\item{fema_decision}{"Approved" or "Denied".}
+\item{fema_decision_date}{The date FEMA settled the request: the date the major
+disaster declaration was granted for an approved request, and FEMA's own
+\code{request_status_date} -- the date the request was turned down -- for a denied one.}
+\item{fema_decision_year}{The calendar year of \code{fema_decision_date}.}
+\item{fema_declaration_request_date}{Date the state filed the request (denied records only).}
+\item{fema_declaration_title}{FEMA's name for the event.}
+\item{fema_requested_incident_types}{FEMA's own classification of the requested incident
+types (denied records only).}
+\item{fema_hazards}{Semicolon-separated hazard categories read from FEMA's
+\code{fema_declaration_title} and \code{fema_requested_incident_types}, on the same category set
+as \code{pda_hazards} so the two can be compared (denied records only).}
+\item{fema_ihp_declared, fema_ia_declared, fema_pa_declared, fema_hm_declared}{FEMA's
+record of whether the declaration turned on the Individuals and Households Program,
+the (pre-2002) Individual Assistance program, Public Assistance, and Hazard
+Mitigation (approved records only; NA for denied ones). A program can be declared
+without appearing in the PDA -- added by a later request -- and requested without
+being declared, so these legitimately diverge from the \verb{pda_*_requested} flags.}
+\item{fema_ihp_requested, fema_ia_requested, fema_pa_requested, fema_hm_requested}{FEMA's
+record of the programs the denied request asked for (denied records only; NA for
+approved ones). Requests for the Individual Assistance umbrella are recorded under
+\code{fema_ihp_requested}; \code{fema_ia_requested} names the pre-2002 Individual Assistance
+program and is FALSE throughout the years the PDA archive covers. \code{fema_ihp_requested}
+is narrower than \code{pda_ia_requested}: a request only for a component program such as
+Disaster Unemployment Assistance sets the \code{pda_} flag but not FEMA's.}
+\item{pda_matched}{TRUE where a PDA report was matched to this FEMA record.}
+\item{pda_warnings}{Semicolon-separated descriptions of the data quality problems
+found on this record -- a value that cannot be what its field measures, a
+footnote number standing in for a dollar total, damage categories that do not
+add up, a report contradicting itself about whether a program was requested,
+and the like. NA where no problem was found. Values are returned as parsed, so
+each problem can be checked against its source report. Named \code{warnings} when
+\code{join_outcomes = FALSE}.}
+\item{pda_match_quality}{How the match was made, or NA where none was. "exact" covers an
+approved request joined on its disaster number; a denied request whose determination
+date is the denial decision date within the same state; and a denied request whose
+report names no state -- a tribal report names the tribe instead -- matched on the
+determination date alone, where exactly one denial in the country shares that date
+and it agrees with the report on hazard or shares a word with its title.
+"approximate" is a denied request matched instead to the nearest denial of the same
+hazard type within seven days either side of the date the report prints, and says how
+many days apart the two records are. "manual" is a link established by hand,
+for the case no rule can settle: two of a state's requests decided on the same day,
+with FEMA naming neither in a way that ties it to its report.}
+\item{pda_path}{The local file path to the source PDA PDF.}
+\item{pda_decision}{Type of decision the report announces: "approved", "denial",
+"appeal_approved", or "appeal_denial". Finer-grained than \code{fema_decision}, which
+does not distinguish an original decision from one made on appeal.}
+\item{pda_declaration_title}{The report's description of the event.}
+\item{pda_date_determined}{Date the PDA determination was made.}
+\item{pda_tribal_flag}{1 where the request came from a tribal government, 0 otherwise.
+Set where the report title contains any of "Native", "Tribe", "Tribes", "Tribal",
+"Indians", "Nation", "Band", "Pueblo", "Rancheria", "Reservation", "Village",
+"Traditional Council", or "IRA Council". This drives the extraction logic for many fields
+because tribal records are formatted differently than state/territorial records.}
+\item{pda_hazards}{Semicolon-separated hazard categories ("flooding; landslide") read from
+\code{pda_declaration_title}. NA where no keyword matched.}
+\item{pda_pa_requested}{1 where Public Assistance was requested, 0 where the report states
+"Public Assistance - Not requested". Where a report says the program was not
+requested but reports values for it anyway, or states no values while its narrative
+does not name the program, the flag is settled from the report's opening narrative
+-- see \code{requested_from_narrative}.}
+\item{pda_pa_preemptive_declaration}{1 where the report states that the "requirement for a
+joint PDA may be waived", meaning the event was severe enough that FEMA proceeded
+without conducting a joint preliminary damage assessment first; 0 otherwise.}
+\item{pda_pa_primary_impact}{The primary type of impact described for Public Assistance
+purposes.}
+\item{pda_pa_cost_estimate_total}{Estimated total Public Assistance cost.}
+\item{pda_pa_per_capita_impact_statewide}{Statewide (or territory/commonwealth) per capita
+impact amount.}
+\item{pda_pa_per_capita_impact_indicator_statewide}{FEMA's statutory statewide per capita
+\emph{threshold} in dollars for the relevant year (observed range 1.24--1.94). A report
+that states no value, or states one outside the published range, is given the value
+the other reports of its fiscal year state; the indicator is uniform within a fiscal
+year, so this fill is very low risk.}
+\item{pda_pa_per_capita_impact_countywide}{Raw text of countywide per capita impact ratios (may list
 multiple values across affected counties for a multi-county event).}
-\item{pa_per_capita_impact_indicator_countywide}{FEMA's statutory countywide per capita
-threshold in dollars (observed range 3.11--4.60), on the same basis as the statewide
-indicator above.}
-\item{pa_per_capita_impact_countywide_max}{Maximum countywide per capita impact ratio parsed
+\item{pda_pa_per_capita_impact_indicator_countywide}{FEMA's statutory countywide per capita
+threshold in dollars, on the same basis as the statewide indicator above.}
+\item{pda_pa_per_capita_impact_countywide_max}{Maximum countywide per capita impact ratio parsed
 from \code{pa_per_capita_impact_countywide}.}
-\item{pa_per_capita_impact_countywide_min}{Minimum countywide per capita impact ratio parsed
+\item{pda_pa_per_capita_impact_countywide_min}{Minimum countywide per capita impact ratio parsed
 from \code{pa_per_capita_impact_countywide}.}
-\item{ia_requested}{1 if Individual Assistance was requested, 0 otherwise.}
-\item{ia_residences_impacted}{Total residences impacted.}
-\item{ia_residences_destroyed}{Number of residences destroyed.}
-\item{ia_residences_major_damage}{Number of residences with major damage.}
-\item{ia_residences_minor_damage}{Number of residences with minor damage.}
-\item{ia_residences_affected}{Number of residences affected (lowest damage category).}
-\item{ia_residences_insured_total_percent}{Percentage of impacted residences with any insurance coverage.}
-\item{ia_residences_insured_flood_percent}{Percentage of impacted residences with flood insurance coverage.}
-\item{ia_households_poverty_percent}{Percentage of households in poverty (or low income,
+\item{pda_pa_threshold_ratio}{\code{pa_per_capita_impact_statewide} divided by
+\code{pa_per_capita_impact_indicator_statewide}: the estimated per capita damage expressed as
+a multiple of the statutory threshold, so a value above 1 means the threshold was
+exceeded.}
+\item{pda_ia_requested}{1 where Individual Assistance was requested, 0 where the report states
+"Individual Assistance - Not requested". Where a report states no Individual
+Assistance values and its opening narrative does not name the program among those
+requested, the flag is set to 0 -- see \code{requested_from_narrative}. Individual
+Assistance is read broadly: a request only for one of its component programs
+(Crisis Counseling, Disaster Unemployment Assistance, Disaster Legal Services,
+Disaster Case Management) counts, so this flag can be 1 where FEMA's own
+\code{fema_ihp_requested} is FALSE.}
+\item{pda_requested_from_narrative}{Names the program whose requested flag was settled from
+the report's opening narrative ("ia", "pa", or "ia; pa"), NA otherwise. The narrative is
+consulted only where the report disagrees with itself: the summary says a program
+was not requested while the report prints values for it, or the report prints no
+values while the narrative does not name the program. A narrative naming any
+component program of Individual Assistance counts as requesting Individual
+Assistance.}
+\item{pda_ia_residences_impacted}{Total residences impacted.}
+\item{pda_ia_residences_destroyed}{Number of residences destroyed.}
+\item{pda_ia_residences_major_damage}{Number of residences with major damage.}
+\item{pda_ia_residences_minor_damage}{Number of residences with minor damage.}
+\item{pda_ia_residences_affected}{Number of residences affected (lowest damage category).}
+\item{pda_ia_residences_insured_total_percent}{Percentage of impacted residences with any insurance coverage.}
+\item{pda_ia_residences_insured_flood_percent}{Percentage of impacted residences with flood insurance coverage.}
+\item{pda_ia_households_poverty_percent}{Percentage of households in poverty (or low income,
 depending on report vintage).}
-\item{ia_households_owner_percent}{Percentage of households that are owner-occupied.}
-\item{ia_population_other_government_assistance_percent}{Percentage of the population receiving
+\item{pda_ia_households_owner_percent}{Percentage of households that are owner-occupied.}
+\item{pda_ia_population_other_government_assistance_percent}{Percentage of the population receiving
 other government assistance (e.g. SSI, SNAP).}
-\item{ia_pre_disaster_unemployment_percent}{Pre-disaster unemployment rate.}
-\item{ia_65plus_percent}{Percentage of the population age 65 and older.}
-\item{ia_18below_percent}{Percentage of the population age 18 and under.}
-\item{ia_disability_percent}{Percentage of the population with a disability.}
-\item{ia_ihp_cost_to_capacity_ratio}{Individuals and Households Program (IHP) Cost to Capacity (ICC) ratio.}
-\item{ia_cost_estimate_total}{Estimated total Individual Assistance cost.}
-\item{text}{The cleaned text extracted from the PDA PDF used to derive the fields above.}
+\item{pda_ia_pre_disaster_unemployment_percent}{Pre-disaster unemployment rate.}
+\item{pda_ia_65plus_percent}{Percentage of the population age 65 and older.}
+\item{pda_ia_18below_percent}{Percentage of the population age 18 and under.}
+\item{pda_ia_disability_percent}{Percentage of the population with a disability.}
+\item{pda_ia_ihp_cost_to_capacity_ratio}{Individuals and Households Program (IHP) Cost to Capacity (ICC) ratio.}
+\item{pda_ia_cost_estimate_total}{Estimated total Individual Assistance cost.}
+\item{pda_cost_estimate_ia_pa_total}{\code{pa_cost_estimate_total} plus \code{ia_cost_estimate_total},
+treating a missing program cost as zero; 0 where neither program reported one.}
+\item{pda_text}{The cleaned text extracted from the PDA PDF used to derive the fields above.}
 }
 }
 \description{
 Retrieves data extracted from PDF preliminary damage assessment (PDA)
-reports submitted to FEMA for disaster declarations.
+reports published by FEMA as part of the disaster declaration request process.
 }
 \details{
 Data are extracted from PDF reports hosted at
@@ -90,22 +189,24 @@ Owing to the unstructured nature of the source documents, some fields may be inc
 in the data returned by the function, though significant quality checks have been
 implemented in an effort to produce a high-quality dataset.
 
-Before the data are returned -- whether newly generated or read from the cache --
-they are checked for the ways that parsing an unstructured PDF fails silently:
-values that are not finite numbers, negative counts, percentages outside 0-100,
-cost estimates small enough to be a label's footnote number rather than a total,
-demographic shares of exactly zero (the signature of a blank field whose footnote
-number was read as the value),
-statutory per capita thresholds outside their published range, damage categories
-summing to more than the stated total of impacted residences, values recorded for
-a program the report says was not requested, values far above the rest of their
-column, malformed or missing disaster numbers, implausible determination dates,
-and columns that are almost entirely empty among the reports that should state
-them. Anything found is raised as a single \code{warning()} naming example source
-reports; the values themselves are returned as parsed, so each can be checked
-against its PDF. The share of each field that is missing among the reports that
-requested the program and were approved is reported with \code{message()}, since
-whether a given rate is a problem is a judgment rather than a rule.
+With \code{join_outcomes = TRUE} (the default), the PDA data are attached to
+FEMA's own structured records of which declaration requests were declared and
+denied. FEMA's
+\code{DisasterDeclarationsSummaries} (granted major disaster declarations) and
+\code{DeclarationDenials} (turned-down major disaster requests) datasets are
+authoritative, so every such record is returned, with the PDA columns empty
+where no report could be matched to it. An approved request is matched on
+its disaster number. A denied request never receives a disaster number, so
+it is matched on state, on the decision date the report prints, and on
+agreement between the hazards the two records describe, with anything
+ambiguous left unmatched; \code{match_quality} records
+which of these applied. Set \code{join_outcomes = FALSE} for the reports alone.
+
+Data quality is reported through a single consolidated warning: how many
+records carry values that may be incorrect -- each such record's specific
+issue(s) are written to the \code{pda_warnings} column -- and how many PDA
+reports could not be matched to an authoritative FEMA declaration or
+denial and are therefore absent from the returned data.
 }
 \examples{
 \dontrun{
diff --git a/man/scrape_pda_pdfs.Rd b/man/scrape_pda_pdfs.Rd
index 89bb5f0..ffeb1b4 100644
--- a/man/scrape_pda_pdfs.Rd
+++ b/man/scrape_pda_pdfs.Rd
@@ -27,7 +27,7 @@ collisions are resolved only against the pages requested, so a name could be
 assigned that a page outside the range also claims.}
 
 \item{max_pages}{A guard against an unbounded walk if the listing ever stops
-returning empty pages. Raises an error if reached.}
+returning empty pages.}
 
 \item{attempts_per_page}{How many times to try a listing page before treating
 it as a failure.}
@@ -49,7 +49,7 @@ containing \code{url}, \code{destination_file}, and \code{status} (\code{"cached
 to \code{cache_directory}.
 }
 \description{
-Downloads every PDA report PDF that FEMA publishes into a local
+Downloads every PDA report that FEMA publishes into a local
 directory, so that \code{get_preliminary_damage_assessments()} has a complete and
 current set of source documents to parse. Run this before regenerating the
 dataset; \code{get_preliminary_damage_assessments()} parses whatever is already on
@@ -57,27 +57,12 @@ disk and never fetches anything itself.
 }
 \details{
 Walks every page of FEMA's PDA report listing at
-https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports,
-advancing until a page returns no PDF links, and downloads any report not
-already present in \code{cache_directory}. Because the full listing is traversed on
-every run, the set of files on disk after a successful run is the complete set
-of reports FEMA publishes -- coverage does not depend on the caller working
-out which page numbers hold new reports.
+https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports
+and downloads any report not
+already present in \code{cache_directory}.
 
 A page that errors is retried, and exhausting the retries raises an error
-rather than ending the walk. This matters because a transient failure and a
-genuinely empty final page are otherwise indistinguishable, and treating the
-former as the end of the listing would silently truncate the archive.
-
-The listing is server-rendered, so the PDF links are present in the HTML that
-\code{httr::GET()} returns and no headless browser is needed. An earlier version
-used \code{rvest::read_html_live()}, which requires \code{chromote}; that dependency is
-not declared by this package and is frequently absent, which made the
-function fail outright rather than merely run slowly.
-
-Note that FEMA's bot protection rejects requests that do not carry a
-browser-like \code{User-Agent}, and rejects them from some networks regardless, so
-a failure here is not necessarily a change to the listing.
+rather than ending the walk.
 }
 \examples{
 \dontrun{
diff --git a/tests/testthat/test-get_preliminary_damage_assessments.R b/tests/testthat/test-get_preliminary_damage_assessments.R
index 7e5a7c1..4e8d9fc 100644
--- a/tests/testthat/test-get_preliminary_damage_assessments.R
+++ b/tests/testthat/test-get_preliminary_damage_assessments.R
@@ -13,3 +13,353 @@ test_that("get_preliminary_damage_assessments function signature is correct", {
   f <- get_preliminary_damage_assessments
   expect_true(formals(f)$use_cache)
 })
+
+test_that("get_preliminary_damage_assessments joins outcomes by default", {
+  expect_true("join_outcomes" %in% names(formals(get_preliminary_damage_assessments)))
+  expect_true(formals(get_preliminary_damage_assessments)$join_outcomes)
+})
+
+test_that("the event title keeps the event and drops everything else", {
+  reports <- tibble::tibble(
+    text = c(
+      "Colorado wildfire report text",
+      "North Carolina report text",
+      "Kentucky report text"),
+    event_title = c(
+      "Preliminary Damage Assessment Report - Colorado - Marshall Fire",
+      "Flooding in North Carolina",
+      "Commonwealth of Kentucky Severe Storms and Flooding FEMA-4595-DR Declared July 29, 2022"))
+
+  cleaned <- add_pda_derived_columns(reports)
+
+  expect_equal(cleaned$event_title[1], "Marshall Fire")
+  ## a state name inside the description is part of the description
+  expect_equal(cleaned$event_title[2], "Flooding in North Carolina")
+  expect_equal(cleaned$event_title[3], "Severe Storms and Flooding")
+  expect_equal(cleaned$state_name, c("Colorado", "North Carolina", "Kentucky"))
+})
+
+test_that("hazard categories are consistent across differing source wordings", {
+  reports <- tibble::tibble(
+    text = c("Vermont report text", "Louisiana report text", "Alaska report text"),
+    event_title = c(
+      "Severe Storms, Floods, Landslides, and Mudslides",
+      "Hurricane Ida",
+      "Structure Fire"))
+
+  cleaned <- add_pda_derived_columns(reports)
+
+  ## "Floods" and "Flooding" both become "flooding"; mudslides and landslides
+  ## are one category rather than two names for the same thing
+  expect_equal(cleaned$hazards[1], "flooding; severe storm; landslide")
+  expect_equal(cleaned$hazards[2], "hurricane")
+  expect_equal(cleaned$hazards[3], "wildfire")
+})
+
+test_that("shared hazard counts distinguish partial from complete disagreement", {
+  expect_equal(
+    shared_hazard_category_count(
+      c("flooding; severe storm", "flooding", "wildfire"),
+      c("flooding; severe storm", "wildfire", NA_character_)),
+    c(2L, 0L, NA_integer_))
+})
+
+test_that("the hand-checked denial links are well formed", {
+  links <- manual_pda_denial_links()
+
+  expect_named(links, c("pda_file", "denial_id", "note"))
+  ## a report may be linked once and a denial claimed once, or the table
+  ## itself would create the ambiguity it exists to resolve
+  expect_equal(anyDuplicated(links$pda_file), 0)
+  expect_equal(anyDuplicated(links$denial_id), 0)
+  ## the denial identifier is "state | date | FEMA's incident name"
+  expect_true(all(stringr::str_detect(links$denial_id, "^.+ \\| \\d{4}-\\d{2}-\\d{2} \\| .+$")))
+  expect_true(all(nchar(links$note) > 0))
+})
+
+test_that("shared title words ignore the words common to every tribal name", {
+  ## "Tribe" and "Band" appear in most tribal names, so counting them would make
+  ## any two tribal records look related
+  expect_equal(
+    shared_title_word_count(
+      "Spokane Tribe - Cayuse Mountain Wildfire",
+      "Cayuse Mountain Fire"),
+    2L)
+  expect_equal(
+    shared_title_word_count("Oglala Sioux Tribe", "Cheyenne River Sioux Band"),
+    1L)
+  expect_equal(shared_title_word_count("Navajo Nation", "Tribe"), NA_integer_)
+})
+
+test_that("FEMA's abbreviated tropical storm names are recognised", {
+  ## FEMA writes "TS Cristobal" in its own turndown records
+  expect_equal(extract_hazard_categories("TS Cristobal"), "tropical storm")
+  expect_equal(
+    extract_hazard_categories("Tropical Storm Cristobal"), "tropical storm")
+  ## the abbreviation must be a word on its own, not a fragment of another
+  expect_true(is.na(extract_hazard_categories("Tsunami warning aftermath")) |
+    !stringr::str_detect(
+      extract_hazard_categories("Tsunami warning aftermath"), "tropical"))
+})
+
+test_that("tropical and coastal storm count as the same event when compared", {
+  ## the same landfalling system is a tropical storm to the state and a coastal
+  ## storm to FEMA; the two labels are kept apart but agree for matching
+  expect_equal(shared_hazard_category_count("tropical storm", "coastal storm"), 1L)
+  expect_equal(
+    shared_hazard_category_count("flooding; tropical storm", "flooding; coastal storm"),
+    2L)
+  ## unrelated hazards still disagree
+  expect_equal(shared_hazard_category_count("wildfire", "coastal storm"), 0L)
+})
+
+test_that("a missing statewide indicator is filled from its fiscal year's reports", {
+  ## the indicator is national and changes on 1 October, so reports from
+  ## November 2019 and March 2020 belong to the same fiscal year as each other.
+  ## The fourth report is a tribal request, which is assessed against the same
+  ## national figure and so is filled in like any other.
+  reports <- tibble::tibble(
+    text = rep("Statewide Per Capita Impact Indicator for FY20", 4),
+    event_date_determined = as.Date(c(
+      "2019-11-05", "2020-03-10", "2020-06-01", "2020-05-05")),
+    event_native_flag = c(0, 0, 0, 1),
+    pa_per_capita_impact_indicator_statewide = c(1.53, 1.53, NA, NA))
+
+  filled <- suppressMessages(impute_statewide_indicator(reports))
+
+  expect_equal(
+    filled$pa_per_capita_impact_indicator_statewide, c(1.53, 1.53, 1.53, 1.53))
+  expect_equal(
+    filled$pa_per_capita_impact_indicator_statewide_source,
+    c("reported", "reported", "imputed", "imputed"))
+})
+
+test_that("a stated value outside the published range is replaced", {
+  ## two reports state 1.53 and one states 3.11, which is outside the published
+  ## range and is the countywide threshold printed in the statewide row
+  reports <- tibble::tibble(
+    text = rep("Statewide Per Capita Impact Indicator for FY20", 4),
+    event_date_determined = as.Date(rep("2020-05-05", 4)),
+    event_native_flag = rep(0, 4),
+    pa_per_capita_impact_indicator_statewide = c(1.53, 1.53, 3.11, NA))
+
+  filled <- suppressMessages(impute_statewide_indicator(reports))
+
+  ## the out-of-range value does not set the year's value ...
+  expect_equal(filled$pa_per_capita_impact_indicator_statewide[4], 1.53)
+  ## ... and is itself replaced, which is said so in the source column
+  expect_equal(filled$pa_per_capita_impact_indicator_statewide[3], 1.53)
+  expect_equal(
+    filled$pa_per_capita_impact_indicator_statewide_source,
+    c("reported", "reported",
+      "imputed, replacing a stated value outside the published range", "imputed"))
+})
+
+test_that("only the statewide indicator is overwritten when a value is implausible", {
+  ## the countywide threshold is equally out of its own range here, and is left
+  ## exactly as parsed
+  reports <- tibble::tibble(
+    text = rep("Statewide Per Capita Impact Indicator for FY20", 2),
+    event_date_determined = as.Date(rep("2020-05-05", 2)),
+    event_native_flag = c(0, 0),
+    pa_per_capita_impact_indicator_statewide = c(1.53, 3.11),
+    pa_per_capita_impact_indicator_countywide = c(3.84, 1.00),
+    pa_per_capita_impact_statewide = c(2.10, 999))
+
+  filled <- suppressMessages(impute_statewide_indicator(reports))
+
+  expect_equal(filled$pa_per_capita_impact_indicator_countywide, c(3.84, 1.00))
+  expect_equal(filled$pa_per_capita_impact_statewide, c(2.10, 999))
+})
+
+test_that("an October-to-December fill is marked as possibly a year too recent", {
+  reports <- tibble::tibble(
+    text = rep("Statewide Per Capita Impact Indicator for FY24", 3),
+    event_date_determined = as.Date(c("2023-10-11", "2024-03-01", "2024-02-01")),
+    event_native_flag = rep(0, 3),
+    pa_per_capita_impact_indicator_statewide = c(NA, NA, 1.84))
+
+  filled <- suppressMessages(impute_statewide_indicator(reports))
+
+  expect_equal(
+    filled$pa_per_capita_impact_indicator_statewide_source,
+    c("imputed, and may be one fiscal year too recent", "imputed", "reported"))
+})
+
+test_that("a fiscal year with no reported value is left empty", {
+  reports <- tibble::tibble(
+    text = rep("Statewide Per Capita Impact Indicator for FY20", 2),
+    event_date_determined = as.Date(c("2020-05-05", "2020-06-06")),
+    event_native_flag = c(0, 0),
+    pa_per_capita_impact_indicator_statewide = c(NA_real_, NA_real_))
+
+  filled <- suppressMessages(impute_statewide_indicator(reports))
+
+  expect_true(all(is.na(filled$pa_per_capita_impact_indicator_statewide)))
+  expect_true(all(is.na(filled$pa_per_capita_impact_indicator_statewide_source)))
+})
+
+test_that("an Alaska Native village is recognised as a tribal requester", {
+  ## the pattern the extraction applies to the report title
+  is_tribal <- function(title) {
+    stringr::str_detect(
+      title,
+      stringr::regex(
+        stringr::str_c(
+          "\\b(Native|Tribe|Tribes|Tribal|Indians|Nation|Band|Pueblo|",
+          "Rancheria|Reservation|Villages?)\\b|",
+          "\\b(Traditional|IRA) Council\\b"),
+        ignore_case = TRUE)) }
+
+  ## names an Alaska Native village with none of the older keywords
+  expect_true(is_tribal("Newtok Village - Flooding, Persistent Erosion"))
+  expect_true(is_tribal("Native Village of Kivalina - Severe Storms"))
+  expect_true(is_tribal("Chevak Traditional Council - Building Fire"))
+  ## and does not fire on an ordinary state request
+  expect_false(is_tribal("Severe Storms, Straight-line Winds, and Flooding"))
+  expect_false(is_tribal("National Weather Service reported flooding"))
+})
+
+test_that("the narrative settles a report that contradicts itself", {
+  ## the first report says Public Assistance was not requested and then reports
+  ## a cost for it; the second says the same but reports nothing, so there is no
+  ## contradiction to settle
+  reports <- tibble::tibble(
+    path = c("a.pdf", "b.pdf"),
+    text = rep(paste(
+      "The Governor requested a declaration for Public Assistance for four",
+      "counties and Hazard Mitigation statewide."), 2),
+    ia_requested = c(0, 0),
+    pa_requested = c(0, 0),
+    pa_cost_estimate_total = c(1e6, NA))
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$pa_requested, c(1, 0))
+  expect_equal(settled$requested_from_narrative, c("pa", NA))
+})
+
+test_that("a component-program request reads as a request for Individual Assistance", {
+  ## Individual Assistance is read broadly: a request for any of its component
+  ## programs -- Crisis Counseling, Disaster Unemployment Assistance, Disaster
+  ## Legal Services, Disaster Case Management -- counts, whether or not the
+  ## sentence names Individual Assistance itself. This is deliberately wider
+  ## than FEMA's ihProgramRequested field, which records only the Individuals
+  ## and Households Program.
+  component <- c(
+    "requested a declaration for Crisis Counseling under the Individual Assistance program for three counties.",
+    "requested a declaration for the Crisis Counseling Program and Disaster Unemployment Assistance under the Individual Assistance program for one county.",
+    "requested a declaration for Disaster Unemployment Assistance for two counties.",
+    "requested a declaration for Disaster Legal Services and Disaster Case Management statewide.")
+  full <- c(
+    "requested a declaration for Individual Assistance, including the Crisis Counseling Program, for two counties.",
+    "requested a declaration for the Individuals and Households Program, Crisis Counseling, for one county.")
+
+  settle <- function(sentences) {
+    suppressMessages(resolve_requested_flags(tibble::tibble(
+      path = seq_along(sentences), text = sentences,
+      ia_requested = 0, pa_requested = 1,
+      ia_residences_impacted = 10)))$ia_requested }
+
+  expect_equal(settle(component), c(1, 1, 1, 1))
+  expect_equal(settle(full), c(1, 1))
+})
+
+test_that("an SBA-loan-only request is not a request for Individual Assistance", {
+  ## The 2025 Wisconsin "Lack of Snow" denial: the Governor requested only a
+  ## Small Business Administration Economic Injury Loan, the summary carries no
+  ## "Not requested" line for Individual Assistance, and the only non-dash
+  ## Individual Assistance figures are a literal 0 and $0. The zeros are
+  ## placeholders, not measurements, and the SBA sentence is a readable
+  ## narrative that requests neither program.
+  reports <- tibble::tibble(
+    path = "wi.pdf",
+    text = paste(
+      "The Governor requested a declaration for a Small Business",
+      "Administration (SBA) Economic Injury Loan for all 72 counties.",
+      "Summary of Damage Assessment Information."),
+    ia_requested = 1, pa_requested = 0,
+    ia_residences_impacted = NA_real_,
+    ia_ihp_cost_to_capacity_ratio = 0,
+    ia_cost_estimate_total = 0)
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$ia_requested, 0)
+  expect_equal(settled$requested_from_narrative, "ia")
+})
+
+test_that("a report with no narrative sentence keeps the summary's flag", {
+  reports <- tibble::tibble(
+    path = "a.pdf",
+    text = "Summary of Damage Assessment Information. Individual Assistance - Not requested",
+    ia_requested = 0, pa_requested = 1,
+    ia_residences_impacted = 10)
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$ia_requested, 0)
+  expect_true(is.na(settled$requested_from_narrative))
+})
+
+test_that("a program the narrative never names, with no values, is not requested", {
+  ## FEMA-4585-DR (Alaska): the Governor requested Public Assistance and Hazard
+  ## Mitigation only, the summary omits the "Not requested" wording, and every
+  ## Individual Assistance field is a placeholder. The summary alone would read
+  ## this as a request for Individual Assistance.
+  reports <- tibble::tibble(
+    path = "4585.pdf",
+    text = paste(
+      "The Governor requested Public Assistance program for five areas and",
+      "Hazard Mitigation statewide. Summary of Damage Assessment Information.",
+      "Individual Assistance Total Number of Residences Impacted: -"),
+    ia_requested = 1, pa_requested = 1,
+    ia_residences_impacted = NA_real_,
+    pa_cost_estimate_total = 24047546)
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$ia_requested, 0)
+  expect_equal(settled$pa_requested, 1)
+  expect_equal(settled$requested_from_narrative, "ia")
+})
+
+test_that("a program the narrative names keeps its flag even with no values", {
+  ## FEMA-4707-DR (Hoopa Valley Tribe): the narrative does request Individual
+  ## Assistance, and the summary reports N/A throughout because no damage
+  ## figures were collected. The flag stays at 1.
+  reports <- tibble::tibble(
+    path = "4707.pdf",
+    text = paste(
+      "The Chairman requested a declaration for the Individuals and Households",
+      "program under the Individual Assistance, Public Assistance, including",
+      "direct federal assistance and snow assistance, and Hazard Mitigation for",
+      "the Hoopa Valley Tribe. Summary of Damage Assessment Information."),
+    ia_requested = 1, pa_requested = 1,
+    ia_residences_impacted = NA_real_,
+    pa_cost_estimate_total = 649321)
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$ia_requested, 1)
+  expect_true(is.na(settled$requested_from_narrative))
+})
+
+test_that("an unreadable narrative never sets a flag on its own", {
+  ## A report whose request sentences name none of the four programs is not
+  ## evidence either way, so the summary's flag stands.
+  reports <- tibble::tibble(
+    path = "denial.pdf",
+    text = paste(
+      "The Governor's request was denied on appeal.",
+      "Summary of Damage Assessment Information."),
+    ia_requested = 1, pa_requested = 1,
+    ia_residences_impacted = NA_real_,
+    pa_cost_estimate_total = NA_real_)
+
+  settled <- suppressMessages(resolve_requested_flags(reports))
+
+  expect_equal(settled$ia_requested, 1)
+  expect_equal(settled$pa_requested, 1)
+  expect_true(is.na(settled$requested_from_narrative))
+})
diff --git a/vignettes/preliminary_damage_assessments.Rmd.orig b/vignettes/preliminary_damage_assessments.Rmd.orig
index ee9317f..d351565 100644
--- a/vignettes/preliminary_damage_assessments.Rmd.orig
+++ b/vignettes/preliminary_damage_assessments.Rmd.orig
@@ -41,6 +41,26 @@ its official outcome. We then ask a simple question: **do the requests FEMA
 approves actually clear the Public Assistance per-capita threshold, and do the
 ones it denies fall short?**
 
+## PDA Data Preparation
+
+Because FEMA publishes only PDF reports of preliminary damage assessments---rather
+than formally structuring these data, maintaining an ongoing database, and publishing
+the data via an API---the package provides two functions for accessing these data: 
+
+ - `scrape_pda_pdfs()` finds the URLs to every PDA report at 
+  https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports and
+  then systematically downloads these PDFs into a user-specified directory. These PDFs
+  are the basis for the dataset produced by the following function. Because FEMA receives 
+  and the President makes disaster request decisions on an ongoing basis, the results of this
+  function quickly become stale: new PDA reports are available online but are not reflected
+  in the user's specified directory. Accordingly, it is important to re-run this function 
+  frequently if the most up-to-date data are important. The function does not re-download reports
+  that are already saved in the user-specified directory, so after the initial run, which can be 
+  slow, subsequent runs should be very fast--they only add new reports.
+- `get_preliminary_damage_assessments()` walks the user's specified directory and extracts 
+  structured attributes from each PDA report, compiling data from all reports in the directory 
+  into a consistent dataset. 
+
 ## Data sources
 
 | Role | Dataset | Access |
@@ -52,9 +72,11 @@ ones it denies fall short?**
 The two FEMA datasets are *authoritative*: they are FEMA's own structured
 records of what was declared and what was turned down. The PDAs, by contrast,
 are text-extracted from unstructured PDFs and carry the caveats described in
-`?get_preliminary_damage_assessments`. Treating the OpenFEMA records as the
-source of truth for the outcome, and the PDAs as the source of the damage
-estimates, plays to the strengths of each.
+`?get_preliminary_damage_assessments`. `get_preliminary_damage_assessments()` treats the two authoritative datasets as
+defining the universe of requests and maps the PDA reports back onto them, so
+that we can better understand the relationship between preliminary damage
+estimates and disaster declaration decisionmaking. Both FEMA datasets are
+fetched by the function itself; nothing below calls the API directly.
 
 ```{r setup}
 library(climateapi)
@@ -64,183 +86,58 @@ library(urbnthemes)
 set_urbn_defaults(style = "print")
 ```
 
-```{r parameters}
-## PDAs and approved declarations are restricted to requests filed after this
-## year (i.e. 2025 onward). Denials use a one-year-wider window so that a request
-## filed late in the prior year but denied inside the analysis window can still
-## be matched to its PDA.
-pda_min_year = 2024
-denial_min_year = 2023
-```
-
-## Loading and preparing the PDAs
-
-The PDA text names the affected state, so we recover it with a regex built from
-every state and territory name. Names are ordered longest-first so that, for
-example, "West Virginia" is preferred over the substring "Virginia" when both
-could match at the same position.
-
-```{r states-match}
-states_match = tigris::fips_codes %>%
-  distinct(state_name) %>%
-  arrange(desc(str_length(state_name))) %>%
-  pull(state_name) %>%
-  str_c(collapse = "|")
-```
-
 ```{r load-pdas, eval = FALSE}
-pdas = get_preliminary_damage_assessments(use_cache = TRUE)
+scrape_pda_pdfs()
+pda_outcomes = get_preliminary_damage_assessments(use_cache = FALSE)
 ```
 
 ```{r load-pdas-hidden, echo = FALSE}
-pdas = get_preliminary_damage_assessments(use_cache = TRUE)
+## this updates the local cache of all PDF reports
+scrape_pda_pdfs()
+## this extracts attributes from all reports and joins them to FEMA's own
+## records of what was declared and what was denied. use_cache = FALSE ensures
+## the function does not simply return an older dataset, based on the previous
+## set of PDF reports
+pda_outcomes = get_preliminary_damage_assessments(use_cache = FALSE)
 ```
 
-From each PDA we keep the fields needed for the join and the analysis: the
-disaster number (the key for approved requests), the affected state, the
-approve/deny decision parsed from the report, the determination date, the
-per-capita impact figures, and the cost estimates.
-
-```{r prepare-pdas}
-pdas_recent = pdas %>%
-  filter(year(event_date_determined) > pda_min_year) %>%
-  mutate(
-    ## the OpenFEMA disaster number is numeric; the PDA value is character and
-    ## may be NA -- coerce both sides to character so the join keys are comparable
-    disaster_number = as.character(disaster_number),
-    ## a handful of PDA URLs carry a typo'd disaster number. The getter now
-    ## re-derives most of these from the PDF text; these two remaining cases are
-    ## corrected here as a belt-and-suspenders measure.
-    disaster_number = case_when(
-      disaster_number == "4653" ~ "4853",
-      disaster_number == "4657" ~ "4857",
-      TRUE ~ disaster_number),
-    state = str_extract(text, states_match),
-    pda_title = event_title %>%
-      str_remove("Preliminary Damage Assessment Report") %>%
-      ## group the alternation so this matches a literal "(State name)", not a
-      ## bare state name (| binds looser than the surrounding parens otherwise)
-      str_remove(str_c("\\((", states_match, ")\\)")) %>%
-      str_remove("^\\s*[–-]\\s*") %>%
-      str_squish(),
-    decision = case_when(
-      str_detect(event_type, "denial") ~ "Denied",
-      str_detect(event_type, "approv") ~ "Approved"),
-    ## a total damage estimate; 0 when neither program reported a cost
-    cost_estimate_ia_pa_total = rowSums(
-      cbind(pa_cost_estimate_total, ia_cost_estimate_total), na.rm = TRUE)) %>%
-  ## drop PDAs whose state could not be recovered from the text -- they cannot be
-  ## joined to the FEMA records by state
-  filter(!is.na(state), !is.na(decision)) %>%
-  select(
-    disaster_number, decision, state, event_date_determined, pda_title,
-    pa_per_capita_impact_statewide, pa_per_capita_impact_indicator_statewide,
-    pa_cost_estimate_total, ia_cost_estimate_total, cost_estimate_ia_pa_total)
-```
-
-## Loading the authoritative FEMA outcomes
-
-### Approved requests
-
-`DisasterDeclarationsSummaries` returns one row per designated area (usually a
-county), so a single declaration appears many times. We collapse to one row per
-declaration string and translate the state abbreviation to a full name to match
-the PDA state field.
-
-```{r load-declarations}
-declarations_raw = rfema::open_fema(
-  data_set = "DisasterDeclarationsSummaries",
-  ## major disaster declarations only
-  filters = list(declarationType = "=DR"),
-  ask_before_call = FALSE) %>%
-  janitor::clean_names()
-
-declarations = declarations_raw %>%
-  filter(year(declaration_date) > pda_min_year) %>%
-  distinct(fema_declaration_string, .keep_all = TRUE) %>%
-  transmute(
-    disaster_number = as.character(disaster_number),
-    state,
-    declaration_type,
-    declaration_date = lubridate::as_date(declaration_date),
-    declaration_title,
-    decision = "Approved") %>%
-  ## translate the state abbreviation to the full name used by the PDAs
-  left_join(
-    tigris::fips_codes %>% distinct(state_name, state),
-    by = "state",
-    relationship = "many-to-one") %>%
-  select(-state) %>%
-  rename(state = state_name)
-```
-
-### Denied requests
-
-`DeclarationDenials` records requests FEMA turned down. Crucially, a denied
-request never receives an official disaster number, so it cannot be joined on
-that key — a fact that shapes the join strategy below. The state name is already
-spelled out, and the request date stands in for the declaration date.
-
-```{r load-denials}
-denials_raw = rfema::open_fema(
-  data_set = "DeclarationDenials",
-  ask_before_call = FALSE) %>%
-  janitor::clean_names()
-
-denials = denials_raw %>%
-  filter(
-    current_request_status == "Turndown",
-    declaration_request_type == "Major Disaster",
-    year(declaration_request_date) > denial_min_year) %>%
-  transmute(
-    state,
-    declaration_date = lubridate::as_date(declaration_request_date),
-    declaration_title = incident_name,
-    decision = "Denied") %>%
-  mutate(across(where(is.character), str_trim))
-```
-
-## Joining PDAs to their outcomes
-
-The two outcomes require two different joins, because approvals and denials
-carry different keys.
-
-**Approved requests** share a disaster number with the declarations record, so
-we join on `disaster_number`, `state`, and `decision` directly. The join is
-many-to-one: a disaster may have more than one PDA (an original plus an
-appeal), but only one authoritative declaration.
-
-```{r join-approved}
-joined_approved = pdas_recent %>%
-  filter(decision == "Approved") %>%
-  left_join(
-    declarations,
-    by = c("disaster_number", "state", "decision"),
-    relationship = "many-to-one") %>%
-  mutate(matched = !is.na(declaration_date))
-```
-
-**Denied requests** have no disaster number to join on. Instead we match each
-denied PDA to the turndown in the same state whose request date falls closest to
-(and at or before) the PDA's determination date, using a rolling `join_by()`.
-The PDA table is on the left so that the inequality reads in the natural
-direction (`event_date_determined >= declaration_date`).
-
-```{r join-denied}
-joined_denied = pdas_recent %>%
-  filter(decision == "Denied") %>%
-  left_join(
-    denials,
-    by = join_by(
-      state,
-      decision,
-      closest(event_date_determined >= declaration_date)),
-    relationship = "many-to-one") %>%
-  mutate(matched = !is.na(declaration_date)) %>%
-  ## one turndown in this window is a train-derailment request: not a natural
-  ## hazard and not a substantive PDA, so we exclude it from the comparison
-  filter(is.na(declaration_title) | !str_detect(declaration_title, regex("train", ignore_case = TRUE)))
-```
+## What the function does for us
+
+Everything the join requires is done inside
+`get_preliminary_damage_assessments()`, so the vignette does not repeat it. It
+is worth stating what that work is, because the returned columns only make
+sense alongside it.
+
+**The rows are FEMA's, not the reports'.** The function returns one row for
+every granted major disaster declaration and every turned-down major disaster
+request FEMA publishes, going back to the start of both records. A request with
+no usable PDA report keeps its row, with the report columns empty and
+`pda_matched` set to `FALSE`.
+
+**Approvals are matched on the disaster number.** It is unique nationally, so
+it alone identifies the declaration. Where a declaration has more than one
+report -- an original and an appeal -- the most recent is kept, and
+`pda_match_quality` says so.
+
+**Denials are matched on the decision date, checked against the hazard.** A
+denied request never receives a disaster number, so there is no key to join on.
+What a denial report does carry is the date the decision was made, which is the
+turndown's `request_status_date` in FEMA's record. That equality, within a
+state, is the primary match. Where one date matches several of a state's
+turndowns -- FEMA can decide two requests on the same day -- the candidates are
+narrowed by how many hazard categories they share with the report, then by
+elimination, since a turndown can back only one report. Anything still
+ambiguous is left unmatched, counted in the function's consolidated warning,
+rather than guessed at. A report
+with no same-day turndown gets one further chance: the nearest earlier turndown
+within seven days, and only when the hazards agree; those carry an
+`"approximate"` `pda_match_quality` so they stay visible.
+
+The hazard comparison rests on two columns the function derives by keyword:
+`pda_hazards`, read from the report's own event title, and `fema_hazards`, read
+from FEMA's incident name and requested incident types. Both use the same set
+of category names ("flooding", "severe storm", "tornado", and so on), which is
+what makes the two free-text descriptions comparable at all.
 
 ### Did the join succeed?
 
@@ -249,34 +146,27 @@ authoritative FEMA record. A low match rate would mean our outcome labels are
 unreliable.
 
 ```{r match-rate}
-pda_outcomes = bind_rows(joined_approved, joined_denied)
-
 pda_outcomes %>%
-  count(decision, matched) %>%
-  pivot_wider(names_from = matched, values_from = n, names_prefix = "matched_", values_fill = 0)
+  count(fema_decision, pda_matched) %>%
+  pivot_wider(
+    names_from = pda_matched, values_from = n,
+    names_prefix = "matched_", values_fill = 0)
 ```
 
 ## Analysis: does the per-capita threshold predict the outcome?
 
 FEMA's Public Assistance program compares a jurisdiction's estimated per-capita
 damage against a statutory per-capita *indicator* (a dollar threshold that is
-updated annually). We express each PDA as the ratio of the two: a value above
-1.0 means the estimated damage exceeded the threshold.
-
-```{r threshold-ratio}
-pda_outcomes = pda_outcomes %>%
-  mutate(
-    pa_threshold_ratio =
-      pa_per_capita_impact_statewide / pa_per_capita_impact_indicator_statewide)
-```
+updated annually). The function supplies the ratio of the two as `pda_pa_threshold_ratio`: a value
+above 1.0 means the estimated damage exceeded the threshold.
 
 If the threshold drove the decision, approved requests would sit above the line
 and denials below it.
 
 ```{r ratio-boxplot, fig.alt = "Boxplot with jittered points of the ratio of estimated statewide per-capita impact to FEMA's Public Assistance per-capita indicator, with a dashed line at a ratio of one."}
 pda_outcomes %>%
-  filter(!is.na(pa_threshold_ratio)) %>%
-  ggplot(aes(x = decision, y = pa_threshold_ratio, color = decision)) +
+  filter(!is.na(pda_pa_threshold_ratio)) %>%
+  ggplot(aes(x = fema_decision, y = pda_pa_threshold_ratio, color = fema_decision)) +
   geom_hline(yintercept = 1, linetype = "dashed", color = "grey40") +
   geom_boxplot(outlier.shape = NA) +
   geom_jitter(width = 0.15, alpha = 0.5) +
@@ -296,11 +186,11 @@ estimate shows how the two dimensions interact.
 
 ```{r ratio-cost-scatter, fig.alt = "Scatterplot of the per-capita threshold ratio against total estimated damage, with a dashed vertical line at a ratio of one."}
 pda_outcomes %>%
-  filter(!is.na(pa_threshold_ratio), cost_estimate_ia_pa_total > 0) %>%
+  filter(!is.na(pda_pa_threshold_ratio), pda_cost_estimate_ia_pa_total > 0) %>%
   ggplot(aes(
-    x = pa_threshold_ratio,
-    y = cost_estimate_ia_pa_total,
-    color = decision)) +
+    x = pda_pa_threshold_ratio,
+    y = pda_cost_estimate_ia_pa_total,
+    color = fema_decision)) +
   geom_vline(xintercept = 1, linetype = "dashed", color = "grey40") +
   geom_point(alpha = 0.7, size = 2) +
   scale_y_continuous(
@@ -315,14 +205,20 @@ pda_outcomes %>%
 
 ## Caveats
 
-- **State recovery is best-effort.** The affected state is extracted from free
-  text and is set to the first state name that appears; a report that mentions a
-  neighboring state first could be mislabeled. PDAs with no recoverable state are
-  dropped before the join.
+- **State recovery is best-effort.** The affected state is extracted from the
+  report's free text and is set to the first state name that appears; a report
+  that mentions a neighboring state first could be mislabeled. Approvals are
+  unaffected, because they are matched on the disaster number alone, but a
+  denial report with no recoverable state -- a tribal request names none --
+  cannot be matched and its damage estimates do not appear.
 - **Denied requests are matched by date, not by key.** Because turndowns lack a
-  disaster number, the denied join relies on a closest-date heuristic within a
-  state. Two denials close together in time in the same state could be matched
-  imperfectly.
+  disaster number, the denied match uses the exact turndown decision date within
+  a state, validated by hazard-category agreement, with ambiguous or
+  hazard-inconsistent candidates left unmatched. A turndown FEMA has not
+  yet published in `DeclarationDenials` therefore appears as an unmatched PDA
+  rather than as a wrong match. The hazard categories themselves come from
+  keyword matching on free text, so an unusual hazard description could leave a
+  category unassigned (which weakens, but does not break, the validation).
 - **`disaster_number` reliability.** For FEMA's newest filename convention
   (`FY25…`, `FY26…`), the disaster number is recovered from the PDF body rather
   than the filename; see `?get_preliminary_damage_assessments` for details.
diff --git a/vignettes/preliminary_damage_assessments.qmd b/vignettes/preliminary_damage_assessments.qmd
new file mode 100644
index 0000000..b917530
--- /dev/null
+++ b/vignettes/preliminary_damage_assessments.qmd
@@ -0,0 +1,330 @@
+---
+title: "Preliminary Damage Assessments and Declaration Outcomes"
+format:
+  html:
+    toc: true
+    toc-depth: 3
+    embed-resources: true
+    fig-width: 8
+    fig-height: 6
+    fig-dpi: 300
+execute:
+  echo: true
+  ## warnings and messages are shown here, unlike in the package vignette:
+  ## `get_preliminary_damage_assessments()` reports its data quality problems and
+  ## its unmatched reports that way, and when you are stepping through the
+  ## analysis those are things you want to read rather than suppress
+  warning: true
+  message: true
+editor_options:
+  chunk_output_type: console
+---
+
+```{r}
+#| label: options
+#| include: false
+
+options(scipen = 999)
+```
+
+## Overview
+
+When a state, territory, or tribal government believes an event exceeds its
+capacity to respond, it requests a major disaster declaration from the
+president. Before that request is granted or denied, FEMA and its partners
+conduct a *preliminary damage assessment* (PDA) that estimates the scale of
+the damage and compares it against the statutory thresholds FEMA uses to gauge
+whether federal assistance is warranted.
+
+`get_preliminary_damage_assessments()` extracts these estimates from the PDF
+PDA reports FEMA publishes and joins them to FEMA's own record of which
+requests were granted and which were turned down, so that each report carries
+its official outcome. We then ask a simple question: **do the requests FEMA
+approves actually clear the Public Assistance per-capita threshold, and do the
+ones it denies fall short?**
+
+This is a step-through version of the package vignette
+(`vignettes/preliminary_damage_assessments.Rmd.orig`). It runs the same
+analysis, but it exposes the two switches that decide how long the first chunk
+takes, and it adds sections for inspecting what the join produced. Run it a
+chunk at a time; nothing below depends on being knitted as a whole.
+
+## PDA Data Preparation
+
+Because FEMA publishes only PDF reports of preliminary damage assessments---rather
+than formally structuring these data, maintaining an ongoing database, and publishing
+the data via an API---the package provides two functions for accessing these data: 
+
+ - `scrape_pda_pdfs()` finds the URLs to every PDA report at 
+  https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports and
+  then systematically downloads these PDFs into a user-specified directory. These PDFs
+  are the basis for the dataset produced by the following function. Because FEMA receives 
+  and the President makes disaster request decisions on an ongoing basis, the results of this
+  function quickly become stale: new PDA reports are available online but are not reflected
+  in the user's specified directory. Accordingly, it is important to re-run this function 
+  frequently if the most up-to-date data are important. The function does not re-download reports
+  that are already saved in the user-specified directory, so after the initial run, which can be 
+  slow, subsequent runs should be very fast--they only add new reports.
+- `get_preliminary_damage_assessments()` walks the user's specified directory and extracts 
+  structured attributes from each PDA report, compiling data from all reports in the directory 
+  into a consistent dataset. 
+
+## Data sources
+
+| Role | Dataset | Access |
+|---|---|---|
+| Damage estimates | PDA reports | `climateapi::get_preliminary_damage_assessments()` |
+| Approved requests | `DisasterDeclarationsSummaries` | OpenFEMA, via `rfema::open_fema()` |
+| Denied requests | `DeclarationDenials` | OpenFEMA, via `rfema::open_fema()` |
+
+The two FEMA datasets are *authoritative*: they are FEMA's own structured
+records of what was declared and what was turned down. The PDAs, by contrast,
+are text-extracted from unstructured PDFs and carry the caveats described in
+`?get_preliminary_damage_assessments`. `get_preliminary_damage_assessments()`
+treats the two authoritative datasets as defining the universe of requests and
+maps the PDA reports back onto them, so that we can better understand the
+relationship between preliminary damage estimates and disaster declaration
+decisionmaking. Both FEMA datasets are fetched by the function itself; nothing
+below calls the API directly.
+
+```{r}
+#| label: setup
+
+library(climateapi)
+library(tidyverse)
+library(urbnthemes)
+
+## `library(climateapi)` attaches the installed build. If that build predates the
+## `join_outcomes` argument used below, either reinstall the package from this
+## clone (devtools::install()) or, if the Imports are all present in your
+## library, load the source directly instead:
+# devtools::load_all()
+
+set_urbn_defaults(style = "print")
+```
+
+### Two switches worth setting before you run the next chunk
+
+`refresh_reports` controls whether FEMA's report listing is walked and any newly
+published PDFs downloaded. It only adds reports that are not already on disk, so
+after the first run it is quick, but it does need a network connection and
+several minutes.
+
+`rebuild_dataset` controls whether the PDFs are re-parsed. Parsing the full
+archive takes a long time -- there are over 1,300 reports -- so leave it `FALSE`
+while you are working through the analysis and set it `TRUE` when you have
+downloaded new reports or changed the parsing code. The join to FEMA's
+declaration and denial records is redone either way, because those records
+change as FEMA publishes new decisions.
+
+```{r}
+#| label: switches
+
+refresh_reports = FALSE
+rebuild_dataset = FALSE
+```
+
+```{r}
+#| label: load-pdas
+
+if (refresh_reports) { scrape_pda_pdfs() }
+
+pda_outcomes = get_preliminary_damage_assessments(use_cache = !rebuild_dataset)
+
+dim(pda_outcomes)
+```
+
+## What the function does for us
+
+Everything the join requires is done inside
+`get_preliminary_damage_assessments()`, so this document does not repeat it. It
+is worth stating what that work is, because the returned columns only make
+sense alongside it.
+
+**The rows are FEMA's, not the reports'.** The function returns one row for
+every granted major disaster declaration and every turned-down major disaster
+request FEMA publishes, going back to the start of both records. A request with
+no usable PDA report keeps its row, with the report columns empty and
+`pda_matched` set to `FALSE`.
+
+**Approvals are matched on the disaster number.** It is unique nationally, so
+it alone identifies the declaration. Where a declaration has more than one
+report -- an original and an appeal -- the most recent is kept, and
+`match_quality` says so.
+
+**Denials are matched on the decision date, checked against the hazard.** A
+denied request never receives a disaster number, so there is no key to join on.
+What a denial report does carry is the date the decision was made, which is the
+turndown's `request_status_date` in FEMA's record. That equality, within a
+state, is the primary match. Where one date matches several of a state's
+turndowns -- FEMA can decide two requests on the same day -- the candidates are
+narrowed by how many hazard categories they share with the report, then by
+elimination, since a turndown can back only one report. Anything still
+ambiguous is left unmatched, counted in the function's consolidated warning,
+rather than guessed at. A report
+with no same-day turndown gets one further chance: the nearest earlier turndown
+within seven days, and only when the hazards agree; those carry an
+`"approximate"` `match_quality` so they stay visible.
+
+The hazard comparison rests on two columns the function derives by keyword:
+`hazards`, read from the report's own event title, and `denial_hazards`, read
+from FEMA's incident name and requested incident types. Both use the same set
+of category names ("flooding", "severe storm", "tornado", and so on), which is
+what makes the two free-text descriptions comparable at all.
+
+The identifying columns, so you can see the shape of a row before going
+further:
+
+```{r}
+#| label: peek
+
+pda_outcomes %>%
+  select(
+    disaster_number, state_name, decision, declaration_date,
+    declaration_request_date, declaration_title, event_title, hazards,
+    pda_matched, match_quality) %>%
+  glimpse()
+```
+
+### Did the join succeed?
+
+Before analyzing the joined data, we confirm that the PDAs actually matched an
+authoritative FEMA record. A low match rate would mean our outcome labels are
+unreliable.
+
+```{r}
+#| label: match-rate
+
+pda_outcomes %>%
+  count(decision, pda_matched) %>%
+  pivot_wider(
+    names_from = pda_matched, values_from = n,
+    names_prefix = "matched_", values_fill = 0)
+```
+
+Most unmatched rows are older requests FEMA published no PDA report for, which
+is the expected shape of a full-universe dataset rather than a failure. It does
+mean that any analysis of the report fields has to filter on `pda_matched`.
+
+`match_quality` says how each match was made. Anything other than an exact
+match is worth reading before you rely on it.
+
+```{r}
+#| label: match-quality
+
+pda_outcomes %>%
+  filter(pda_matched) %>%
+  count(match_quality, sort = TRUE)
+```
+
+### Auditing the denied matches by eye
+
+Denials are the matches to check, because they are made on a date and a hazard
+rather than on a key. This is every denied match with the evidence for it side
+by side: the report's own title and hazards against FEMA's.
+
+```{r}
+#| label: denied-match-evidence
+
+pda_outcomes %>%
+  filter(pda_matched, decision == "Denied") %>%
+  transmute(
+    state_name,
+    event_title,
+    hazards,
+    declaration_title,
+    denial_hazards,
+    requested_incident_types,
+    event_date_determined,
+    declaration_request_date,
+    match_quality = str_extract(match_quality, "^[a-z]+")) %>%
+  arrange(desc(event_date_determined)) %>%
+  print(n = 25)
+```
+
+## Analysis: does the per-capita threshold predict the outcome?
+
+FEMA's Public Assistance program compares a jurisdiction's estimated per-capita
+damage against a statutory per-capita *indicator* (a dollar threshold that is
+updated annually). The function supplies the ratio of the two as
+`pa_threshold_ratio`: a value above 1.0 means the estimated damage exceeded the
+threshold.
+
+If the threshold drove the decision, approved requests would sit above the line
+and denials below it.
+
+```{r}
+#| label: ratio-boxplot
+#| fig-alt: "Boxplot with jittered points of the ratio of estimated statewide per-capita impact to FEMA's Public Assistance per-capita indicator, with a dashed line at a ratio of one."
+
+pda_outcomes %>%
+  filter(!is.na(pa_threshold_ratio)) %>%
+  ggplot(aes(x = decision, y = pa_threshold_ratio, color = decision)) +
+  geom_hline(yintercept = 1, linetype = "dashed", color = "grey40") +
+  geom_boxplot(outlier.shape = NA) +
+  geom_jitter(width = 0.15, alpha = 0.5) +
+  labs(
+    title = "Do approved requests clear the Public Assistance per-capita threshold?",
+    subtitle = "Ratio of estimated statewide per-capita impact to FEMA's statutory indicator",
+    x = NULL,
+    y = "Per-capita impact ÷ threshold") +
+  theme(legend.position = "none")
+```
+
+The relationship is imperfect, which is the point: the per-capita indicator is
+one input among several (insurance coverage, localized impacts, prior-year
+disaster burden), so some sub-threshold requests are approved and some
+above-threshold requests are denied. Plotting the ratio against the total cost
+estimate shows how the two dimensions interact.
+
+```{r}
+#| label: ratio-cost-scatter
+#| fig-alt: "Scatterplot of the per-capita threshold ratio against total estimated damage, with a dashed vertical line at a ratio of one."
+
+pda_outcomes %>%
+  filter(!is.na(pa_threshold_ratio), cost_estimate_ia_pa_total > 0) %>%
+  ggplot(aes(
+    x = pa_threshold_ratio,
+    y = cost_estimate_ia_pa_total,
+    color = decision)) +
+  geom_vline(xintercept = 1, linetype = "dashed", color = "grey40") +
+  geom_point(alpha = 0.7, size = 2) +
+  scale_y_continuous(
+    labels = scales::label_dollar(scale_cut = scales::cut_short_scale())) +
+  labs(
+    title = "Threshold ratio versus total estimated damage",
+    subtitle = "Combined Individual and Public Assistance cost estimate",
+    x = "Per-capita impact ÷ threshold",
+    y = "Total estimated cost",
+    color = "Decision")
+```
+
+## Caveats
+
+- **State recovery is best-effort.** The affected state is extracted from the
+  report's free text and is set to the first state name that appears; a report
+  that mentions a neighboring state first could be mislabeled. Approvals are
+  unaffected, because they are matched on the disaster number alone, but a
+  denial report with no recoverable state -- a tribal request names none --
+  cannot be matched and its damage estimates do not appear.
+- **Denied requests are matched by date, not by key.** Because turndowns lack a
+  disaster number, the denied match uses the exact turndown decision date within
+  a state, validated by hazard-category agreement, with ambiguous or
+  hazard-inconsistent candidates left unmatched. A turndown FEMA has not
+  yet published in `DeclarationDenials` therefore appears as an unmatched PDA
+  rather than as a wrong match. The hazard categories themselves come from
+  keyword matching on free text, so an unusual hazard description could leave a
+  category unassigned (which weakens, but does not break, the validation).
+- **`disaster_number` reliability.** For FEMA's newest filename convention
+  (`FY25…`, `FY26…`), the disaster number is recovered from the PDF body rather
+  than the filename; see `?get_preliminary_damage_assessments` for details.
+- **Per-capita fields are text-extracted.** The `pa_per_capita_impact_*`
+  fields come from parsing PDFs and can be missing or malformed for individual
+  reports; rows with missing values are excluded from the plots.
+
+## See also
+
+- `get_preliminary_damage_assessments()`: the PDA extraction itself
+- `get_fema_disaster_declarations()`: FEMA disaster declarations
+- `get_public_assistance()`: obligated Public Assistance funding
+- `get_ihp_registrations()`: Individual and Households Program registrations
diff --git a/vignettes/preliminary_damage_assessments_original.Rmd b/vignettes/preliminary_damage_assessments_original.Rmd
new file mode 100644
index 0000000..d3d7d59
--- /dev/null
+++ b/vignettes/preliminary_damage_assessments_original.Rmd
@@ -0,0 +1,151 @@
+---
+title: "Preliminary Damage Assessments and Declaration Outcomes"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Preliminary Damage Assessments and Declaration Outcomes}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  warning = FALSE,
+  message = FALSE,
+  fig.width = 8,
+  fig.height = 6,
+  dpi = 300,
+  eval = TRUE,
+  echo = TRUE)
+
+options(scipen = 999)
+```
+
+## Overview
+
+When a state, territory, or tribal government believes an event exceeds its
+capacity to respond, it requests a major disaster declaration from the
+president. Before that request is granted or denied, FEMA and its partners
+conduct a *preliminary damage assessment* (PDA) that estimates the scale of
+the damage and compares it against the statutory thresholds FEMA uses to gauge
+whether federal assistance is warranted.
+
+`get_preliminary_damage_assessments()` extracts these estimates from the
+PDA reports FEMA publishes, and then joins them to authoritative datasets from
+FEMA describing disaster declaration request approvals and denials. 
+
+These combined data are valuable because they provide important information about
+the characteristics of disasters--at an early stage, hence "preliminary"--that is
+used directly to assess whether these disasters merit federal assistance. Unique attributes
+available only from PDAs include estimates of damages to public infrastructure and housing,
+along with counts of the numbers of housing units impacted, by level of impact. 
+
+## Data sources
+
+| Role | Dataset | Access |
+|---|---|---|
+| Damage estimates | PDA reports | `climateapi::get_preliminary_damage_assessments()` |
+| Approved requests | `DisasterDeclarationsSummaries` | OpenFEMA, via `rfema::open_fema()` |
+| Denied requests | `DeclarationDenials` | OpenFEMA, via `rfema::open_fema()` |
+
+The two FEMA datasets are *authoritative*: they are FEMA's own structured
+records of what was declared and what was turned down. The PDAs, by contrast,
+are text-extracted from unstructured PDFs and carry the caveats described in
+`?get_preliminary_damage_assessments`. In this piece, we treat observations 
+from the authoritative FEMA datasets as definining the universe of declarations,
+and we map PDAs back to this universe so that we can better understand the 
+relationships between preliminary damages and disaster declaration decisionmaking. 
+
+```{r setup}
+library(climateapi)
+library(tidyverse)
+library(urbnthemes)
+
+set_urbn_defaults(style = "print")
+```
+
+## PDA Data Preparation
+
+Because FEMA publishes only PDF reports of preliminary damage assessments---rather
+than formally structuring these data, maintaining an ongoing database, and publishing
+the data via an API---the package provides two functions for accessing these data: 
+
+ - `scrape_pda_pdfs()` finds the URLs to every PDA report at 
+  https://www.fema.gov/disaster/how-declared/preliminary-damage-assessments/reports and
+  then systematically downloads these PDFs into a user-specified directory. These PDFs
+  are the basis for the dataset produced by the following function. Because FEMA receives 
+  and the President makes disaster request decisions on an ongoing basis, the results of this
+  function quickly become stale: new PDA reports are available online but are not reflected
+  in the user's specified directory. Accordingly, it is important to re-run this function 
+  frequently if the most up-to-date data are important. The function does not re-download reports
+  that are already saved in the user-specified directory, so after the initial run, which can be 
+  slow, subsequent runs should be very fast--they only add new reports.
+- `get_preliminary_damage_assessments()` walks the user's specified directory and extracts 
+  structured attributes from each PDA report, compiling data from all reports in the directory 
+  into a consistent dataset. 
+
+```{r load-pdas, eval = FALSE}
+scrape_pda_pdfs()
+pdas = get_preliminary_damage_assessments(use_cache = FALSE)
+```
+
+```{r load-pdas-hidden, echo = FALSE}
+## this updates the local cache of all PDF reports
+scrape_pda_pdfs()
+## this extracts attributes from all reports
+## use_cache = FALSE ensures the function doesn't simply return
+## an older dataset (based on the previous set of PDF reports)
+pdas = get_preliminary_damage_assessments(use_cache = FALSE)
+```
+
+
+## Analysis
+
+With our data in hand, it's trivial to summarize the universe of disaster declaration requests
+over time:
+
+```{r}
+pdas %>%
+  ggplot() +
+  geom_bar(aes(x = fema_decision_year, fill = fema_decision)) +
+  scale_x_continuous(breaks = seq(1950, 2030, by = 10))
+```
+
+But access to systematic information on damages and housing impacts are novel, and
+speak to how FEMA and presidents have made decisions over time.
+
+```{r}
+pdas %>%
+  filter(pda_matched == 1, pda_pa_requested == 1) %>%
+  ggplot(aes(x = fema_decision, y = log(pda_pa_threshold_ratio), color = fema_decision)) +
+  geom_boxplot(fill = NA) +
+  labs(
+    title = "Many denied requests surpass the damages threshold used by FEMA" %>% str_wrap(130),
+    x = "", 
+    y = "Logged ratio of PA per-capita damages relative to the per-capita indidcator") 
+
+pdas %>%
+  filter(pda_matched == 1, pda_pa_requested == 1, fema_decision_year > 2007) %>%
+  mutate(
+    president = case_when(
+      fema_decision_year %in% c(2008:2012) ~ "Obama 1",
+      fema_decision_year %in% c(2013:2016) ~ "Obama 2",
+      fema_decision_year %in% c(2017:2020) ~ "Trump 1",
+      fema_decision_year %in% c(2021:2024) ~ "Biden 1",
+      fema_decision_year %in% c(2025:2028) ~ "Trump 2"),
+    president = factor(president, levels = c("Obama 1", "Obama 2", "Trump 1", "Biden 1", "Trump 2"), ordered = TRUE)) %>%
+  ggplot(aes(x = fema_decision, y = log(pda_pa_threshold_ratio), color = fema_decision)) +
+  geom_jitter(alpha = .2) +
+  geom_boxplot(outliers = FALSE, fill = NA) +
+  facet_wrap(~ president, nrow = 1) +
+  labs(
+    title = "Many denied requests surpass the damages threshold used by FEMA" %>% str_wrap(130),
+    x = "", 
+    y = "Logged ratio of PA per-capita damages relative to the per-capita indidcator") 
+```
+
+FEMA's Public Assistance program compares a jurisdiction's estimated per-capita
+damage against a statutory per-capita *indicator* (a dollar threshold that is
+updated annually). We express each PDA as the ratio of the two: a value above
+1.0 means the estimated damage exceeded the threshold.