@mailwoman/tiger 9.4.0 → 10.1.0

package/out/tract.d.ts

@@ -7,7 +7,7 @@ import type { GeoFeature, MultiPolygonLiteral } from "@mailwoman/spatial";
 import type { TIGERProperty, TIGERPropertyRecord } from "#constants";
 import type { FIPSTractGeoID, GeoIDPart, ParsedGeoIDTractLevel } from "#geoid";
 /**
- * @title TIGER Tract
+ * @title tiger Tract
  * @public
  */
 export interface TIGERTract extends ParsedGeoIDTractLevel {
@@ -18,8 +18,8 @@ export interface TIGERTract extends ParsedGeoIDTractLevel {
      */
     GEOID: FIPSTractGeoID;
     /**
-     * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks with holes, or
-     * islands.
+     * The geometry of the tabulated block, typically a polygon, but may be a
+     * multi-polygon for blocks with holes, or islands.
      *
      * @title Geometry
      */

package/out/tsconfig.test.tsbuildinfo

@@ -1 +1 @@
-{"root":["../test/unit/sdk/redistricting.test.ts"],"version":"6.0.3"}
+{"version":"7.0.2","root":["../lib/files.test.ts","../sdk/redistricting.test.ts"],"packageJsons":["../../../node_modules/@googlemaps/google-maps-services-js/package.json","../../../node_modules/@standard-schema/spec/package.json","../../../node_modules/@types/chai/package.json","../../../node_modules/@types/deep-eql/package.json","../../../node_modules/@types/node/package.json","../../../node_modules/@vitest/browser-playwright/package.json","../../../node_modules/@vitest/coverage-v8/package.json","../../../node_modules/@vitest/expect/package.json","../../../node_modules/@vitest/mocker/package.json","../../../node_modules/@vitest/pretty-format/package.json","../../../node_modules/@vitest/runner/package.json","../../../node_modules/@vitest/snapshot/package.json","../../../node_modules/@vitest/spy/package.json","../../../node_modules/@vitest/utils/package.json","../../../node_modules/agentkeepalive/package.json","../../../node_modules/assertion-error/package.json","../../../node_modules/axios/package.json","../../../node_modules/buffer/package.json","../../../node_modules/chai/package.json","../../../node_modules/deep-eql/package.json","../../../node_modules/esbuild/package.json","../../../node_modules/events/package.json","../../../node_modules/expect-type/package.json","../../../node_modules/jiti/package.json","../../../node_modules/jsdom/package.json","../../../node_modules/punycode/package.json","../../../node_modules/retry-axios/package.json","../../../node_modules/string_decoder/package.json","../../../node_modules/tagged-tag/package.json","../../../node_modules/terser/package.json","../../../node_modules/tinybench/package.json","../../../node_modules/tinyrainbow/package.json","../../../node_modules/type-fest/package.json","../../../node_modules/undici-types/package.json","../../../node_modules/vite/package.json","../../../node_modules/vitest/package.json","../../../node_modules/yaml/package.json","../../annotations/package.json","../../spatial/package.json","../package.json"],"missingPackageJsons":["../../../node_modules/@edge-runtime/vm/package.json","../../../node_modules/@googlemaps/google-maps-services-js/dist/geocode/package.json","../../../node_modules/@googlemaps/google-maps-services-js/dist/package.json","../../../node_modules/@googlemaps/google-maps-services-js/dist/places/package.json","../../../node_modules/@googlemaps/google-maps-services-js/dist/roads/package.json","../../../node_modules/@opentelemetry/api/package.json","../../../node_modules/@standard-schema/spec/dist/package.json","../../../node_modules/@types/assert/package.json","../../../node_modules/@types/assert/strict/package.json","../../../node_modules/@types/async_hooks/package.json","../../../node_modules/@types/child_process/package.json","../../../node_modules/@types/cluster/package.json","../../../node_modules/@types/console/package.json","../../../node_modules/@types/constants/package.json","../../../node_modules/@types/crypto/package.json","../../../node_modules/@types/dgram/package.json","../../../node_modules/@types/diagnostics_channel/package.json","../../../node_modules/@types/dns/package.json","../../../node_modules/@types/dns/promises/package.json","../../../node_modules/@types/domain/package.json","../../../node_modules/@types/events/package.json","../../../node_modules/@types/fs/package.json","../../../node_modules/@types/fs/promises/package.json","../../../node_modules/@types/http/package.json","../../../node_modules/@types/http2/package.json","../../../node_modules/@types/https/package.json","../../../node_modules/@types/inspector/package.json","../../../node_modules/@types/inspector/promises/package.json","../../../node_modules/@types/module/package.json","../../../node_modules/@types/net/package.json","../../../node_modules/@types/node/assert/package.json","../../../node_modules/@types/node/dns/package.json","../../../node_modules/@types/node/fs/package.json","../../../node_modules/@types/node/inspector/package.json","../../../node_modules/@types/node/path/package.json","../../../node_modules/@types/node/readline/package.json","../../../node_modules/@types/node/stream/package.json","../../../node_modules/@types/node/test/package.json","../../../node_modules/@types/node/timers/package.json","../../../node_modules/@types/node/util/package.json","../../../node_modules/@types/node/web-globals/package.json","../../../node_modules/@types/node/zlib/package.json","../../../node_modules/@types/os/package.json","../../../node_modules/@types/path/package.json","../../../node_modules/@types/path/posix/package.json","../../../node_modules/@types/path/win32/package.json","../../../node_modules/@types/perf_hooks/package.json","../../../node_modules/@types/process/package.json","../../../node_modules/@types/punycode/package.json","../../../node_modules/@types/querystring/package.json","../../../node_modules/@types/readline/package.json","../../../node_modules/@types/readline/promises/package.json","../../../node_modules/@types/repl/package.json","../../../node_modules/@types/stream/consumers/package.json","../../../node_modules/@types/stream/iter/package.json","../../../node_modules/@types/stream/package.json","../../../node_modules/@types/stream/promises/package.json","../../../node_modules/@types/stream/web/package.json","../../../node_modules/@types/string_decoder/package.json","../../../node_modules/@types/timers/package.json","../../../node_modules/@types/timers/promises/package.json","../../../node_modules/@types/tls/package.json","../../../node_modules/@types/trace_events/package.json","../../../node_modules/@types/tty/package.json","../../../node_modules/@types/url/package.json","../../../node_modules/@types/util/package.json","../../../node_modules/@types/util/types/package.json","../../../node_modules/@types/v8/package.json","../../../node_modules/@types/vm/package.json","../../../node_modules/@types/wasi/package.json","../../../node_modules/@types/worker_threads/package.json","../../../node_modules/@types/zlib/package.json","../../../node_modules/@vitejs/devtools/package.json","../../../node_modules/@vitest/browser-preview/package.json","../../../node_modules/@vitest/browser-webdriverio/package.json","../../../node_modules/@vitest/coverage-istanbul/package.json","../../../node_modules/@vitest/expect/dist/package.json","../../../node_modules/@vitest/mocker/dist/package.json","../../../node_modules/@vitest/pretty-format/dist/package.json","../../../node_modules/@vitest/runner/dist/package.json","../../../node_modules/@vitest/runner/utils/package.json","../../../node_modules/@vitest/snapshot/dist/package.json","../../../node_modules/@vitest/spy/dist/package.json","../../../node_modules/@vitest/ui/package.json","../../../node_modules/@vitest/utils/diff/package.json","../../../node_modules/@vitest/utils/display/package.json","../../../node_modules/@vitest/utils/dist/package.json","../../../node_modules/assert/package.json","../../../node_modules/assert/strict/package.json","../../../node_modules/async_hooks/package.json","../../../node_modules/child_process/package.json","../../../node_modules/cluster/package.json","../../../node_modules/console/package.json","../../../node_modules/constants/package.json","../../../node_modules/crypto/package.json","../../../node_modules/dgram/package.json","../../../node_modules/diagnostics_channel/package.json","../../../node_modules/dns/package.json","../../../node_modules/dns/promises/package.json","../../../node_modules/domain/package.json","../../../node_modules/expect-type/dist/package.json","../../../node_modules/fs/package.json","../../../node_modules/fs/promises/package.json","../../../node_modules/happy-dom/package.json","../../../node_modules/http/package.json","../../../node_modules/http2/package.json","../../../node_modules/https/package.json","../../../node_modules/inspector/package.json","../../../node_modules/inspector/promises/package.json","../../../node_modules/less/package.json","../../../node_modules/module/package.json","../../../node_modules/msw/package.json","../../../node_modules/net/package.json","../../../node_modules/os/package.json","../../../node_modules/path/package.json","../../../node_modules/path/posix/package.json","../../../node_modules/path/win32/package.json","../../../node_modules/perf_hooks/package.json","../../../node_modules/process/package.json","../../../node_modules/querystring/package.json","../../../node_modules/readline/package.json","../../../node_modules/readline/promises/package.json","../../../node_modules/repl/package.json","../../../node_modules/retry-axios/dist/package.json","../../../node_modules/retry-axios/dist/src/package.json","../../../node_modules/sass-embedded/package.json","../../../node_modules/sass/package.json","../../../node_modules/stream/consumers/package.json","../../../node_modules/stream/iter/package.json","../../../node_modules/stream/package.json","../../../node_modules/stream/promises/package.json","../../../node_modules/stream/web/package.json","../../../node_modules/stylus/package.json","../../../node_modules/sugarss/package.json","../../../node_modules/timers/package.json","../../../node_modules/timers/promises/package.json","../../../node_modules/tinybench/dist/package.json","../../../node_modules/tinyrainbow/dist/package.json","../../../node_modules/tls/package.json","../../../node_modules/trace_events/package.json","../../../node_modules/tsx/package.json","../../../node_modules/tty/package.json","../../../node_modules/type-fest/source/internal/package.json","../../../node_modules/type-fest/source/package.json","../../../node_modules/url/package.json","../../../node_modules/util/package.json","../../../node_modules/util/types/package.json","../../../node_modules/v8/package.json","../../../node_modules/vite/dist/node/chunks/package.json","../../../node_modules/vite/dist/node/package.json","../../../node_modules/vite/dist/package.json","../../../node_modules/vite/module-runner/package.json","../../../node_modules/vite/types/package.json","../../../node_modules/vitest/dist/chunks/package.json","../../../node_modules/vitest/dist/package.json","../../../node_modules/vm/package.json","../../../node_modules/wasi/package.json","../../../node_modules/worker_threads/package.json","../../../node_modules/zlib/package.json"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/tiger",
-  "version": "9.4.0",
+  "version": "10.1.0",
   "description": "US Census TIGER/Line data processing and analysis.",
   "keywords": [
     "census",
@@ -25,20 +25,27 @@
   },
   "files": [
     "out/",
-    "*.ts",
-    "*.tsx",
-    "**/*.ts",
-    "**/*.tsx",
-    "!*.test.ts",
-    "!*.test.tsx",
+    "lib/**/*.ts",
+    "lib/**/*.tsx",
+    "sdk/**/*.ts",
+    "tools/**/*.ts",
     "!**/*.test.ts",
     "!**/*.test.tsx",
-    "!__snapshots__/",
-    "!test/**"
+    "!__snapshots__/"
   ],
   "type": "module",
   "sideEffects": false,
   "imports": {
+    "#sdk/*": {
+      "types": "./out/sdk/*.d.ts",
+      "node": "./out/sdk/*.js",
+      "default": "./out/sdk/*.js"
+    },
+    "#tools/*": {
+      "types": "./out/tools/*.d.ts",
+      "node": "./out/tools/*.js",
+      "default": "./out/tools/*.js"
+    },
     "#index": {
       "types": "./out/index.d.ts",
       "node": "./out/index.js",
@@ -52,53 +59,63 @@
   },
   "exports": {
     "./package.json": "./package.json",
-    "./sdk": {
-      "types": "./out/sdk/index.d.ts",
-      "node": "./out/sdk/index.js",
-      "default": "./out/sdk/index.js"
-    },
-    "./tools": {
-      "types": "./out/tools/index.d.ts",
-      "node": "./out/tools/index.js",
-      "default": "./out/tools/index.js"
-    },
     ".": {
       "types": "./out/index.d.ts",
       "node": "./out/index.js",
       "default": "./out/index.js"
     },
-    "./sdk/schema": {
-      "types": "./out/sdk/schema.d.ts",
-      "node": "./out/sdk/schema.js",
-      "default": "./out/sdk/schema.js"
+    "./sdk/*": {
+      "types": "./out/sdk/*.d.ts",
+      "node": "./out/sdk/*.js",
+      "default": "./out/sdk/*.js"
+    },
+    "./tools/*": {
+      "types": "./out/tools/*.d.ts",
+      "node": "./out/tools/*.js",
+      "default": "./out/tools/*.js"
+    },
+    "./*": {
+      "types": "./out/*.d.ts",
+      "node": "./out/*.js",
+      "default": "./out/*.js"
     }
   },
   "publishConfig": {
     "access": "public",
     "exports": {
       "./package.json": "./package.json",
-      "./sdk": {
-        "types": "./out/sdk/index.d.ts",
-        "node": "./out/sdk/index.js",
-        "default": "./out/sdk/index.js"
-      },
-      "./tools": {
-        "types": "./out/tools/index.d.ts",
-        "node": "./out/tools/index.js",
-        "default": "./out/tools/index.js"
-      },
       ".": {
         "types": "./out/index.d.ts",
         "node": "./out/index.js",
         "default": "./out/index.js"
       },
-      "./sdk/schema": {
-        "types": "./out/sdk/schema.d.ts",
-        "node": "./out/sdk/schema.js",
-        "default": "./out/sdk/schema.js"
+      "./sdk/*": {
+        "types": "./out/sdk/*.d.ts",
+        "node": "./out/sdk/*.js",
+        "default": "./out/sdk/*.js"
+      },
+      "./tools/*": {
+        "types": "./out/tools/*.d.ts",
+        "node": "./out/tools/*.js",
+        "default": "./out/tools/*.js"
+      },
+      "./*": {
+        "types": "./out/*.d.ts",
+        "node": "./out/*.js",
+        "default": "./out/*.js"
       }
     },
     "imports": {
+      "#sdk/*": {
+        "types": "./out/sdk/*.d.ts",
+        "node": "./out/sdk/*.js",
+        "default": "./out/sdk/*.js"
+      },
+      "#tools/*": {
+        "types": "./out/tools/*.d.ts",
+        "node": "./out/tools/*.js",
+        "default": "./out/tools/*.js"
+      },
       "#index": {
         "types": "./out/index.d.ts",
         "node": "./out/index.js",
@@ -115,13 +132,13 @@
     "test": "node ./out/sdk/TIGERService.test.js"
   },
   "dependencies": {
-    "@mailwoman/core": "9.4.0",
-    "@mailwoman/spatial": "9.4.0",
-    "@mailwoman/sqlite": "9.4.0",
+    "@mailwoman/core": "10.1.0",
+    "@mailwoman/spatial": "10.1.0",
+    "@mailwoman/sqlite": "10.1.0",
     "@turf/boolean-contains": "^7.4.0",
     "kysely": "^0.29.5",
-    "path-ts": "^2.3.0",
-    "spliterator": "^6.4.1",
+    "path-ts": "^2.5.0",
+    "spliterator": "^8.1.0",
     "type-fest": "^5.9.0"
   },
   "devDependencies": {

package/sdk/download.ts

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Raw `fetch` is deliberate for a multi-gigabyte streamed transfer: `APIClient`'s response caching
+ *   and pacing do not apply.
+ */
+
+import { pathExists } from "@mailwoman/core/fs/readers"
+import { openWriteStream, pipeline, Readable } from "@mailwoman/core/fs/streams"
+import { movePath } from "@mailwoman/core/fs/writers"
+import { verifyZipIntegrity } from "@mailwoman/core/fs/zip"
+import type { PathBuilderLike } from "path-ts"
+
+/**
+ * Download `url` to `dest` unless a valid copy is already there.
+ *
+ * "Valid" means every member's CRC-32 checks out.
+ * An interrupted download otherwise leaves a plausible file that fails later inside ogr2ogr.
+ */
+export async function downloadIfNeeded(url: string, dest: PathBuilderLike): Promise<boolean> {
+	if (await pathExists(dest)) {
+		try {
+			await verifyZipIntegrity(dest)
+
+			return true
+		} catch {
+			// corrupt cache — re-download
+		}
+	}
+
+	const tmp = dest + ".tmp"
+	const res = await fetch(url, { redirect: "follow" })
+
+	if (!res.ok || !res.body) throw new Error(`HTTP ${res.status} fetching ${url}`)
+	await pipeline(Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]), openWriteStream(tmp))
+	await movePath(tmp, dest)
+
+	return false
+}

package/{lib/sdk → sdk}/fetch.ts

@@ -2,45 +2,27 @@
  * @copyright Sister Software.
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Pull TIGER geometry/attributes into a `node:sqlite` database via the Kysely
- *   {@link DatabaseClient}.
- *
- *   Replaces the ad-hoc wget and the retired corpus TIGER build script. Pared down from isp-nexus's
- *   `generate-tiger-tiles.ts` (its per-level column mapping is the spec) into the playpen
- *   `repo-tools` idiom: an async generator of progress events, idempotent, no SpatiaLite.
- *
- *   Three levels:
- *
- *   - `tabblock20` (per state) — tabulation blocks → `tabblock20`, geometry as GeoJSON text.
- *   - `place` (per state) — incorporated/census places → `tiger_places` (attribute-only).
- *   - `addrfeat` (per county) — named street segments + ZIPs → `tiger_streets` (attribute-only).
- *
- *   `tiger_streets` + `tiger_places` match the schema the corpus `tiger` adapter reads, so this is a
- *   drop-in replacement for the retired corpus TIGER build script.
- *
- *   Flow per source unit: download (skips a valid cached zip) → unzip → stream `ogr2ogr -f
- *   GeoJSONSeq` (mapping shapefile columns to the schema, WGS84 for geometry levels) → batched
- *   inserts. Re-running a state replaces its rows.
  */
 
 import { APIClient, pluckResponseData } from "@mailwoman/core/api"
-import { mailwomanDataRoot } from "@mailwoman/core/data-root"
+import { dataRootPath } from "@mailwoman/core/data-root"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { extractZipEntries } from "@mailwoman/core/fs/zip"
-import { ogr2ogrGeoJSONSeq } from "@mailwoman/spatial/tools/ogr-stream"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { ogr2ogrGeoJSONSeq } from "@mailwoman/spatial/tools/ogr/stream"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
-import { dirname, join } from "path-ts"
+import { PathBuilder } from "path-ts"
 
+import type { TIGERBlockTable, TIGERDatabase, TIGERPlaceTable, TIGERStreetTable } from "#schema"
+import { initializeTIGERSchema, TIGER_PRAGMAS } from "#schema"
 import { downloadIfNeeded } from "#sdk/download"
-import type { TIGERBlockTable, TIGERDatabase, TIGERPlaceTable, TIGERStreetTable } from "#sdk/schema"
-import { initializeTIGERSchema, TIGER_PRAGMAS } from "#sdk/schema"
 
 const CENSUS_HOST = "https://www2.census.gov"
-const DEFAULT_DATA_ROOT = mailwomanDataRoot()
+const DEFAULT_DATA_ROOT = dataRootPath()
 
 /**
- * Supported TIGER levels. `tabblock20` is per state + carries geometry; `place`/`addrfeat` are attribute-only.
+ * A TIGER/Line product that {@link fetchTIGER} can load.
+ * Only the `tabblock20` level keeps geometry.
  */
 export type TIGERFetchLevel = "tabblock20" | "place" | "addrfeat"
 
@@ -56,51 +38,73 @@ const LEVEL_TABLE: Record<TIGERFetchLevel, keyof TIGERDatabase> = {
 	addrfeat: "tiger_streets",
 }
 
+/**
+ * Options for {@link fetchTIGER}.
+ */
 export interface FetchTIGEROptions {
 	/**
-	 * Two-digit state FIPS, e.g. `"06"`.
+	 * The two-digit state FIPS code, such as `"06"`.
 	 */
 	stateFIPS: string
+
 	/**
-	 * TIGER level. Default `tabblock20`.
+	 * The TIGER level to fetch.
+	 * The default is `tabblock20`.
 	 */
 	level?: TIGERFetchLevel
+
 	/**
-	 * Vintage. Default 2020 for blocks (matches the 2020 P.L.), 2024 for place/addrfeat (current).
+	 * The TIGER vintage year.
+	 *
+	 * The default is 2020 for blocks to match redistricting data.
+	 * Other levels default to 2024.
 	 */
 	vintage?: number
+
 	/**
-	 * Output SQLite path. Default `<dataRoot>/tiger/tiger.db` (the name the corpus `tiger` adapter reads).
+	 * The output SQLite path.
+	 *
+	 * The default is `<dataRoot>/tiger/tiger.db`, which the corpus `tiger` adapter reads.
 	 */
 	outPath?: string
+
 	/**
-	 * Download cache + default output root.
+	 * The root of the download cache and the default output.
+	 * The default is the Mailwoman data root.
 	 */
 	dataRoot?: string
+
 	/**
-	 * Optional three-digit county FIPS filter (blocks only — addrfeat is already per-county).
+	 * A three-digit county FIPS filter that applies only to the `tabblock20` level.
 	 */
 	county?: string
+
 	/**
-	 * Rows per insert. Default 1000.
+	 * The number of rows per insert batch.
+	 * The default is 1000.
 	 */
 	batchSize?: number
 }
 
+/**
+ * A progress event from {@link fetchTIGER}.
+ *
+ * Each event reports a file downloaded or found in the cache, a shapefile extracted, or rows inserted.
+ */
 export type FetchTIGEREvent =
 	| { phase: "download"; file: string; cached: boolean }
 	| { phase: "extract"; file: string }
 	| { phase: "load"; inserted: number; total: number }
 
+/**
+ * The database path, table name and inserted row count that {@link fetchTIGER} returns.
+ */
 export interface FetchTIGERResult {
 	outPath: string
 	table: string
 	inserted: number
 }
 
-/**
- * The isp-nexus column map for `tabblock20`. Geometry rides along implicitly.
- */
 function blockSelectSQL(layer: string, county?: string): string {
 	const where = county ? ` WHERE COUNTYFP20 = '${county}'` : ""
 
@@ -121,7 +125,6 @@ function selectSQL(level: TIGERFetchLevel, layer: string, county?: string): stri
 		case "place":
 			return `SELECT GEOID AS geoid, NAME AS name, STATEFP AS statefp, LSAD AS lsad, NAMELSAD AS namelsad, CLASSFP AS classfp FROM "${layer}"`
 		case "addrfeat":
-			// ADDRFEAT has no STATEFP column — injected per-row from the state we're fetching.
 			return `SELECT LINEARID AS linearid, FULLNAME AS fullname, ZIPL AS zipl, ZIPR AS zipr FROM "${layer}" WHERE FULLNAME IS NOT NULL AND FULLNAME != ''`
 	}
 }
@@ -161,16 +164,12 @@ function buildRow(level: TIGERFetchLevel, p: Record<string, unknown>, geometry:
 				land_area_sqm: Number(p.land_area_sqm ?? 0),
 				water_area_sqm: Number(p.water_area_sqm ?? 0),
 				population: Number(p.population ?? 0),
-				geometry: JSON.stringify(geometry),
+				geometry: stringifyJSON(geometry),
 			}
 	}
 }
 
-/**
- * Scrape the ADDRFEAT directory listing for a state's county FIPS codes.
- */
 async function discoverCounties(state: string, vintage: number): Promise<string[]> {
-	// The LISTING only — a small HTML index. The per-county archives below stay on raw `fetch`, streaming to disk.
 	const html = await new APIClient({ displayName: "tiger-listing", retry: true })
 		.fetch<string>({ url: `${CENSUS_HOST}/geo/tiger/TIGER${vintage}/ADDRFEAT/`, responseType: "text" })
 		.then(pluckResponseData)
@@ -186,26 +185,25 @@ async function discoverCounties(state: string, vintage: number): Promise<string[
 }
 
 /**
- * Fetch one state's TIGER data at `level` into a SQLite DB. Yields progress; returns the final tally.
+ * Downloads one state's TIGER/Line files at `level`, loads them into a SQLite database
+ * and yields progress events.
+ *
+ * It first deletes the state's existing rows from the target table so that a rerun replaces them.
  */
 export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<FetchTIGEREvent, FetchTIGERResult> {
 	const level = options.level ?? "tabblock20"
 	const vintage = options.vintage ?? (level === "tabblock20" ? 2020 : 2024)
-	const dataRoot = options.dataRoot ?? DEFAULT_DATA_ROOT
+	const dataRoot = PathBuilder.from(options.dataRoot ?? DEFAULT_DATA_ROOT)
 	const batchSize = options.batchSize ?? 1000
 	const state = options.stateFIPS
 	const table = LEVEL_TABLE[level]
 
-	const cacheDir = join(dataRoot, "tiger", String(vintage), state)
-	// Default to a stable, vintage-agnostic `tiger.db` — the filename the corpus `tiger` adapter reads
-	// (run-corpus-build → `${ROOT}/tiger/tiger.db`). The vintage is a content detail, not a path one;
-	// the per-table idempotent delete keeps a re-fetch (newer vintage) clean. The download CACHE stays
-	// vintage-partitioned below so zips don't collide across vintages.
-	const outPath = options.outPath ?? join(dataRoot, "tiger", "tiger.db")
+	const cacheDir = dataRoot("tiger", String(vintage), state)
+
+	const outPath = PathBuilder.from(options.outPath ?? dataRoot("tiger", "tiger.db"))
 	await makeDirectories(cacheDir)
-	await makeDirectories(dirname(outPath))
+	await makeDirectories(outPath.dirname())
 
-	// Source units: one (per-state) for block/place; one per county for addrfeat.
 	const geoCodes = level === "addrfeat" ? await discoverCounties(state, vintage) : [""]
 
 	if (level === "addrfeat" && !geoCodes.length) {
@@ -216,11 +214,6 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 	kdb.exec(TIGER_PRAGMAS)
 	await initializeTIGERSchema(kdb)
 
-	/**
-	 * `level` picks the table AND the row shape, but nothing ties them at the type level: {@link buildRow} returns the
-	 * union and Kysely needs the arm's concrete row. The narrowings below are sound only because `buildRow` switches on
-	 * the SAME `level` — keep the two switches in step, or a row shape reaches the wrong table.
-	 */
 	const insertBatch = async (rows: Row[]): Promise<void> => {
 		if (level === "tabblock20") {
 			await kdb
@@ -241,7 +234,6 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 	}
 
 	try {
-		// Idempotent re-run: drop this state's rows first (state_code for blocks, statefp otherwise).
 		if (level === "tabblock20") {
 			await kdb.deleteFrom("tabblock20").where("state_code", "=", state).execute()
 		} else if (level === "place") {
@@ -264,7 +256,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 		for (const geo of geoCodes) {
 			const unit = level === "addrfeat" ? state + geo : state
 			const zipName = `tl_${vintage}_${unit}_${level}.zip`
-			const zipPath = join(cacheDir, zipName)
+			const zipPath = cacheDir(zipName)
 			const url = `${CENSUS_HOST}/geo/tiger/TIGER${vintage}/${LEVEL_DIR[level]}/${zipName}`
 
 			const cached = await downloadIfNeeded(url, zipPath)
@@ -272,7 +264,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 
 			await extractZipEntries(zipPath, cacheDir)
 			const layer = `tl_${vintage}_${unit}_${level}`
-			const shpPath = join(cacheDir, layer + ".shp")
+			const shpPath = cacheDir(layer + ".shp")
 			yield { phase: "extract", file: layer + ".shp" }
 
 			const args = [
@@ -307,7 +299,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 
 		kdb.exec("PRAGMA wal_checkpoint(TRUNCATE);")
 
-		return { outPath, table, inserted }
+		return { outPath: outPath.toString(), table, inserted }
 	} finally {
 		await kdb.destroy()
 	}