@mailwoman/tiger 9.1.0 → 9.3.0

package/{block-group.ts → lib/block-group.ts}

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { TIGERClassCode } from "./class-code.ts"
-import type { TIGERFunctionalStatus } from "./functional-status.ts"
-import type { LegalStatisticalAreaDescription } from "./legal-statistical-area.ts"
-import type { AdminLevel1Code } from "./state.ts"
+import type { TIGERClassCode } from "#class-code"
+import type { TIGERFunctionalStatus } from "#functional-status"
+import type { LegalStatisticalAreaDescription } from "#legal-statistical-area"
+import type { AdminLevel1Code } from "#state"
 
 /**
  * @title TIGER Block Group

package/{class-code.ts → lib/class-code.ts}

@@ -59,7 +59,7 @@ export const TIGERClassCode = {
 	/**
 	 * A movable barrier across a road.
 	 */
-	Gate: "C3066",
+	Check: "C3066",
 
 	/**
 	 * A structure or barrier where a fee is collected for using a road.

package/{constants.ts → lib/constants.ts}

@@ -4,8 +4,8 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { TIGERClassCode } from "./class-code.ts"
-import type { TIGERFunctionalStatus } from "./functional-status.ts"
+import type { TIGERClassCode } from "#class-code"
+import type { TIGERFunctionalStatus } from "#functional-status"
 import type {
 	GeoIDPart,
 	FIPSBlockCode,
@@ -15,9 +15,9 @@ import type {
 	FIPSCountySubDivisionCode,
 	FIPSPlaceCode,
 	FIPSTractCode,
-} from "./geoid.ts"
-import type { LegalStatisticalAreaDescription } from "./legal-statistical-area.ts"
-import type { FIPSStateCode } from "./state.ts"
+} from "#geoid"
+import type { LegalStatisticalAreaDescription } from "#legal-statistical-area"
+import type { FIPSStateCode } from "#state"
 
 /**
  * A code indicating the classification of the block, i.e. urban or rural.

package/{county-subdivision.ts → lib/county-subdivision.ts}

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { TIGERClassCode } from "./class-code.ts"
-import type { TIGERFunctionalStatus } from "./functional-status.ts"
-import type { LegalStatisticalAreaDescription } from "./legal-statistical-area.ts"
-import type { AdminLevel1Code } from "./state.ts"
+import type { TIGERClassCode } from "#class-code"
+import type { TIGERFunctionalStatus } from "#functional-status"
+import type { LegalStatisticalAreaDescription } from "#legal-statistical-area"
+import type { AdminLevel1Code } from "#state"
 
 /**
  * Census Geographic subdivision of a county.

package/{county.ts → lib/county.ts}

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { TIGERClassCode } from "./class-code.ts"
-import type { TIGERFunctionalStatus } from "./functional-status.ts"
-import type { LegalStatisticalAreaDescription } from "./legal-statistical-area.ts"
-import type { AdminLevel1Code } from "./state.ts"
+import type { TIGERClassCode } from "#class-code"
+import type { TIGERFunctionalStatus } from "#functional-status"
+import type { LegalStatisticalAreaDescription } from "#legal-statistical-area"
+import type { AdminLevel1Code } from "#state"
 
 /**
  * @title TIGER County

package/{files.ts → lib/files.ts}

@@ -6,7 +6,7 @@
  *   TIGER Census data utilities.
  */
 
-import type { AdminLevel1Code } from "./state.ts"
+import type { AdminLevel1Code } from "#state"
 
 //#region Constants
 

package/{geoid.ts → lib/geoid.ts}

@@ -6,7 +6,7 @@
 
 import type { Tagged } from "type-fest"
 
-import type { AdminLevel1Code, FIPSStateCode } from "./state.ts"
+import type { AdminLevel1Code, FIPSStateCode } from "#state"
 
 //#region Tagged FIPS types
 
@@ -301,7 +301,6 @@ export interface ParsedGeoIDBlockLevel {
 	[GeoIDPart.Place]: FIPSPlaceCode
 	[GeoIDPart.BlockGroup]: FIPSBlockGroupCode
 	[GeoIDPart.Block]: FIPSBlockCode
-	[GeoIDPart.BlockGroup]: FIPSBlockGroupCode
 	[GeoIDPart.CongressionalDistrict]: FIPSCongressionalDistrictCode
 }
 
@@ -509,10 +508,10 @@ export const GeoIDInputMatchers = {
  * @see {@linkcode GeoIDInputMatchers} for the input-level matchers.
  */
 const GeoIDComponentMatchers = Object.fromEntries(
-	Object.values(GeoIDPart).map((value) => {
+	Object.values(GeoIDPart).map((value): [GeoIDPart, GeoIDInputMatcher] => {
 		return [value, new GeoIDInputMatcher(value)]
 	})
-) as unknown as Record<GeoIDPart, GeoIDInputMatcher>
+) as Record<GeoIDPart, GeoIDInputMatcher>
 
 /**
  * Type-predicate for checking if a value appears to be a valid GeoID component.

package/lib/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#block-group"
+export * from "#class-code"
+export * from "#constants"
+export * from "#county-subdivision"
+export * from "#county"
+export * from "#files"
+export * from "#functional-status"
+export * from "#geoid"
+export * from "#legal-statistical-area"
+export * from "#state"
+export * from "#tabulation-block"
+export * from "#tract"

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

@@ -14,35 +14,11 @@
  *   never holds it: a web stream piped to a write stream.
  */
 
-import { spawn } from "node:child_process"
-import { createWriteStream, existsSync } from "node:fs"
-import { rename } from "node:fs/promises"
-import { Readable } from "node:stream"
-import { pipeline } from "node:stream/promises"
-
+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"
 
-/**
- * Run a command and resolve its stdout, rejecting with the captured stderr on a non-zero exit.
- *
- * Used for the `unzip -tq` integrity probe below — a shelled-out check rather than a library one because the archives
- * are large and `unzip -t` streams them without materializing the contents.
- */
-export function runCapture(cmd: string, args: string[]): Promise<string> {
-	return new Promise((resolve, reject) => {
-		const child = spawn(cmd, args)
-		let out = ""
-		let err = ""
-		child.stdout.on("data", (d) => (out += d))
-		child.stderr.on("data", (d) => (err += d))
-		child.on("error", reject)
-
-		child.on("close", (code) =>
-			code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${err.slice(0, 500)}`))
-		)
-	})
-}
-
 /**
  * Download `url` to `dest` unless a VALID copy is already there. Returns `true` when the cache was reused, `false` when
  * a download happened.
@@ -52,7 +28,7 @@ export function runCapture(cmd: string, args: string[]): Promise<string> {
  * renames, so `dest` is never a partial archive.
  */
 export async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
-	if (existsSync(dest)) {
+	if (await pathExists(dest)) {
 		try {
 			await verifyZipIntegrity(dest)
 
@@ -66,8 +42,8 @@ export async function downloadIfNeeded(url: string, dest: string): Promise<boole
 	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]), createWriteStream(tmp))
-	await rename(tmp, dest)
+	await pipeline(Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]), openWriteStream(tmp))
+	await movePath(tmp, dest)
 
 	return false
 }

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

@@ -24,23 +24,17 @@
  *   inserts. Re-running a state replaces its rows.
  */
 
-import { spawn } from "node:child_process"
-import { createWriteStream, existsSync } from "node:fs"
-import { mkdir, rename } from "node:fs/promises"
-import { dirname, join } from "node:path"
-import { DatabaseSync } from "node:sqlite"
-import { Readable } from "node:stream"
-import { pipeline } from "node:stream/promises"
-
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+import { mailwomanDataRoot } from "@mailwoman/core/data-root"
+import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { extractZipEntries } from "@mailwoman/core/fs/zip"
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { tryParsingJSON } from "@mailwoman/core/objects"
-import { mailwomanDataRoot } from "@mailwoman/core/utils"
-import { TextSpliterator } from "spliterator"
+import { ogr2ogrGeoJSONSeq } from "@mailwoman/spatial/tools/ogr-stream"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { dirname, join } from "path-ts"
 
-import { downloadIfNeeded } from "./download.ts"
-import type { TIGERBlockTable, TIGERDatabase, TIGERPlaceTable, TIGERStreetTable } from "./schema.ts"
-import { initializeTIGERSchema, TIGER_PRAGMAS } from "./schema.ts"
+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()
@@ -176,10 +170,11 @@ function buildRow(level: TIGERFetchLevel, p: Record<string, unknown>, geometry:
  * Scrape the ADDRFEAT directory listing for a state's county FIPS codes.
  */
 async function discoverCounties(state: string, vintage: number): Promise<string[]> {
-	const res = await fetch(`${CENSUS_HOST}/geo/tiger/TIGER${vintage}/ADDRFEAT/`, { redirect: "follow" })
+	// 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)
 
-	if (!res.ok) throw new Error(`HTTP ${res.status} listing ADDRFEAT for vintage ${vintage}`)
-	const html = await res.text()
 	const re = new RegExp(`tl_${vintage}_${state}(\\d{3})_addrfeat\\.zip`, "g")
 	const counties = new Set<string>()
 
@@ -207,8 +202,8 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 	// 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")
-	await mkdir(cacheDir, { recursive: true })
-	await mkdir(dirname(outPath), { recursive: true })
+	await makeDirectories(cacheDir)
+	await makeDirectories(dirname(outPath))
 
 	// Source units: one (per-state) for block/place; one per county for addrfeat.
 	const geoCodes = level === "addrfeat" ? await discoverCounties(state, vintage) : [""]
@@ -217,11 +212,15 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 		throw new Error(`No ADDRFEAT counties found for state ${state} vintage ${vintage}`)
 	}
 
-	const db = new DatabaseSync(outPath)
-	db.exec(TIGER_PRAGMAS)
-	const kdb = new DatabaseClient<TIGERDatabase>({ database: db })
+	const kdb = new DatabaseClient<TIGERDatabase>(outPath)
+	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
@@ -276,37 +275,21 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 			const shpPath = join(cacheDir, layer + ".shp")
 			yield { phase: "extract", file: layer + ".shp" }
 
-			const child = spawn(
-				"ogr2ogr",
-				[
-					"-f",
-					"GeoJSONSeq",
-					"-t_srs",
-					"EPSG:4326",
-					"-sql",
-					selectSQL(level, layer, options.county),
-					"/vsistdout/",
-					shpPath,
-				],
-				{ stdio: ["ignore", "pipe", "pipe"] }
-			)
-
-			let stderr = ""
-			child.stderr.on("data", (d) => (stderr += d))
-
-			const exited = new Promise<number>((resolve) => {
-				child.on("close", (code) => resolve(code ?? 0))
-			})
-
-			// GeoJSONSeq is line-delimited; per-line `tryParsingJSON` so a malformed record is
-			// tolerated (skipped), not thrown.
-			for await (const line of TextSpliterator.fromAsync(child.stdout)) {
-				if (!line) continue
-
-				const feat = tryParsingJSON<{ properties?: Record<string, unknown>; geometry?: unknown }>(line)
-
-				if (!feat) continue
-
+			const args = [
+				"-f",
+				"GeoJSONSeq",
+				"-t_srs",
+				"EPSG:4326",
+				"-sql",
+				selectSQL(level, layer, options.county),
+				"/vsistdout/",
+				shpPath,
+			]
+
+			for await (const feat of ogr2ogrGeoJSONSeq<{ properties?: Record<string, unknown>; geometry?: unknown }>(
+				args,
+				layer
+			)) {
 				if (!feat.properties) continue
 
 				if (level === "tabblock20" && !feat.geometry) continue
@@ -319,14 +302,10 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 			}
 
 			await flush()
-
-			const code = await exited
-
-			if (code !== 0) throw new Error(`ogr2ogr exited ${code} on ${layer}: ${stderr.slice(0, 500)}`)
 			yield { phase: "load", inserted, total: 0 }
 		}
 
-		db.exec("PRAGMA wal_checkpoint(TRUNCATE);")
+		kdb.exec("PRAGMA wal_checkpoint(TRUNCATE);")
 
 		return { outPath, table, inserted }
 	} finally {

package/lib/sdk/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#sdk/fetch"
+export * from "#sdk/redistricting"
+export * from "#sdk/schema"
+export * from "#sdk/state/index"

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

@@ -16,22 +16,16 @@
  *   https://www2.census.gov/programs-surveys/decennial/2020/data/01-Redistricting_File--PL_94-171/
  */
 
-import { spawn } from "node:child_process"
-import { createWriteStream, existsSync } from "node:fs"
-import { mkdir, rename } from "node:fs/promises"
-import { dirname, join } from "node:path"
-import { DatabaseSync } from "node:sqlite"
-import { Readable } from "node:stream"
-import { pipeline } from "node:stream/promises"
-
+import { mailwomanDataRoot } from "@mailwoman/core/data-root"
+import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { extractZipEntries } from "@mailwoman/core/fs/zip"
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { mailwomanDataRoot } from "@mailwoman/core/utils"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { dirname, join } from "path-ts"
 import { TextSpliterator } from "spliterator"
 
-import { AdminLevel1CodeToAbbreviation, StateName, type AdminLevel1Code } from "../state.ts"
-import { downloadIfNeeded } from "./download.ts"
-import { initializeTIGERSchema, TIGER_PRAGMAS, type PLBlockTable, type TIGERDatabase } from "./schema.ts"
+import { downloadIfNeeded } from "#sdk/download"
+import { initializeTIGERSchema, TIGER_PRAGMAS, type PLBlockTable, type TIGERDatabase } from "#sdk/schema"
+import { AdminLevel1CodeToAbbreviation, StateName, type AdminLevel1Code } from "#state"
 
 const REDISTRICTING_BASE =
 	"https://www2.census.gov/programs-surveys/decennial/2020/data/01-Redistricting_File--PL_94-171"
@@ -52,6 +46,60 @@ const GEO_GEOCODE = 9
 const SEG_LOGRECNO = 4
 const P2 = (fieldNo: number) => 76 + (fieldNo - 1)
 
+/**
+ * Segment 2: FILEID|STUSAB|CHARITER|CIFSN|LOGRECNO(4)| P3×71 | P4×73 | H1×3 — 152 fields, H1 at the tail. Verified
+ * against the real file: `ca000022020.pl`'s state row reads 14,392,140 / 13,475,623 / 916,517, the published CA 2020
+ * figures. `occupied + vacant === housing_units` is the invariant that distinguishes a correct offset from a plausible
+ * one, and {@link parseH1} refuses a row where it does not hold.
+ */
+export const SEG2_FIELD_COUNT = 152
+/**
+ * H0010001 — total housing units, the third-from-last field of a segment-2 row.
+ */
+export const H1_TOTAL = SEG2_FIELD_COUNT - 3
+/**
+ * H0010002 — occupied housing units, the second-from-last field.
+ */
+export const H1_OCCUPIED = SEG2_FIELD_COUNT - 2
+/**
+ * H0010003 — vacant housing units, the last field (and so the one that carries a CRLF file's trailing CR).
+ */
+export const H1_VACANT = SEG2_FIELD_COUNT - 1
+
+export interface H1Counts {
+	housing_units: number
+	occupied: number
+	vacant: number
+}
+
+/**
+ * The three H1 counts from one segment-2 row. The last field carries CRLF's trailing CR when the file has one, so each
+ * field is trimmed before it is read as a number; a row whose counts do not add up is refused rather than stored.
+ */
+export function parseH1(fields: readonly string[]): H1Counts {
+	if (fields.length !== SEG2_FIELD_COUNT) {
+		throw new Error(`segment 2 row has ${fields.length} fields, expected ${SEG2_FIELD_COUNT}`)
+	}
+
+	const counts = {
+		housing_units: Number(fields[H1_TOTAL]!.trim()),
+		occupied: Number(fields[H1_OCCUPIED]!.trim()),
+		vacant: Number(fields[H1_VACANT]!.trim()),
+	}
+
+	if (![counts.housing_units, counts.occupied, counts.vacant].every(Number.isInteger)) {
+		throw new Error(`segment 2 row carries a non-integer H1 count: ${fields.slice(H1_TOTAL).join("|")}`)
+	}
+
+	if (counts.occupied + counts.vacant !== counts.housing_units) {
+		throw new Error(
+			`segment 2 row breaks the H1 invariant: occupied ${counts.occupied} + vacant ${counts.vacant} != housing_units ${counts.housing_units} (LOGRECNO ${fields[SEG_LOGRECNO]})`
+		)
+	}
+
+	return counts
+}
+
 /**
  * The eight P2 categories that partition the total (P0020001), in `pl_block` column order.
  */
@@ -139,8 +187,8 @@ export async function* fetchRedistricting(
 	const cacheDir = join(dataRoot, "census", "redistricting", String(vintage), state)
 	// Same stable `tiger.db` default as fetchTIGER — pl_block lives alongside tabblock20 in one DB.
 	const outPath = options.outPath ?? join(dataRoot, "tiger", "tiger.db")
-	await mkdir(cacheDir, { recursive: true })
-	await mkdir(dirname(outPath), { recursive: true })
+	await makeDirectories(cacheDir)
+	await makeDirectories(dirname(outPath))
 
 	const zipName = `${fileAbbr}${vintage}.pl.zip`
 	const zipPath = join(cacheDir, zipName)
@@ -152,6 +200,7 @@ export async function* fetchRedistricting(
 	await extractZipEntries(zipPath, cacheDir)
 	const geoPath = join(cacheDir, `${fileAbbr}geo${vintage}.pl`)
 	const seg1Path = join(cacheDir, `${fileAbbr}00001${vintage}.pl`)
+	const seg2Path = join(cacheDir, `${fileAbbr}00002${vintage}.pl`)
 	yield { phase: "extract", file: `${fileAbbr}geo${vintage}.pl` }
 
 	// Pass 1: header → LOGRECNO → GEOID for the blocks we want.
@@ -171,9 +220,23 @@ export async function* fetchRedistricting(
 	const total = logToGeoid.size
 	yield { phase: "header", blocks: total }
 
-	const db = new DatabaseSync(outPath)
-	db.exec(TIGER_PRAGMAS)
-	const kdb = new DatabaseClient<TIGERDatabase>({ database: db })
+	// Pass 1b: segment 2 → H1 housing counts for the mapped LOGRECNOs. Read before segment 1 so a block's P2 and H1
+	// land in one row; a mapped block with no segment-2 row is a data defect the load refuses, never a zero.
+	const h1ByLogrecno = new Map<string, H1Counts>()
+
+	await eachLine(seg2Path, (line) => {
+		const f = line.split("|")
+		const logrecno = f[SEG_LOGRECNO] ?? ""
+
+		if (!logToGeoid.has(logrecno)) return
+
+		h1ByLogrecno.set(logrecno, parseH1(f))
+	})
+
+	yield { phase: "extract", file: `${fileAbbr}00002${vintage}.pl` }
+
+	const kdb = new DatabaseClient<TIGERDatabase>(outPath)
+	kdb.exec(TIGER_PRAGMAS)
 	await initializeTIGERSchema(kdb)
 
 	try {
@@ -198,12 +261,20 @@ export async function* fetchRedistricting(
 		for await (const line of TextSpliterator.fromAsync(seg1Path)) {
 			if (!line) continue
 			const f = line.split("|")
-			const geoid = logToGeoid.get(f[SEG_LOGRECNO] ?? "")
+			const logrecno = f[SEG_LOGRECNO] ?? ""
+			const geoid = logToGeoid.get(logrecno)
 
 			if (!geoid) continue
 
+			const h1 = h1ByLogrecno.get(logrecno)
+
+			if (!h1) {
+				throw new Error(`block ${geoid} (LOGRECNO ${logrecno}) has a segment-1 row and no segment-2 row`)
+			}
+
 			batch.push({
 				GEOID: geoid,
+				...h1,
 				pop_total: Number(f[CATEGORY_INDEX.pop_total] ?? 0),
 				hispanic: Number(f[CATEGORY_INDEX.hispanic] ?? 0),
 				white: Number(f[CATEGORY_INDEX.white] ?? 0),
@@ -224,7 +295,7 @@ export async function* fetchRedistricting(
 		await flush()
 
 		yield { phase: "load", inserted, total }
-		db.exec("PRAGMA wal_checkpoint(TRUNCATE);")
+		kdb.exec("PRAGMA wal_checkpoint(TRUNCATE);")
 
 		return { outPath, table: "pl_block", inserted }
 	} finally {

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

@@ -46,6 +46,18 @@ export interface PLBlockTable {
 	nhpi: number
 	other: number
 	multi: number
+	/**
+	 * P.L. 94-171 table H1 — total housing units in the block.
+	 */
+	housing_units: number
+	/**
+	 * H1 occupied. `occupied + vacant === housing_units` by construction; the reader refuses a row where it is not.
+	 */
+	occupied: number
+	/**
+	 * H1 vacant.
+	 */
+	vacant: number
 }
 
 /**
@@ -106,6 +118,25 @@ PRAGMA journal_mode = WAL;
  * The `text(N)` length hints in the prior raw DDL were documentary only (SQLite uses TEXT affinity regardless); the
  * lengths live on the {@link TIGERBlockTable} interface instead.
  */
+/**
+ * Refuse a `pl_block` built before the H1 columns existed. `createTable(...).ifNotExists()` leaves an older table as it
+ * is, and the next load would fail on the first insert with a message about a column, not about the cause. The table is
+ * derived (the redistricting command reloads it state by state), so the remedy is a rebuild: drop it and re-run
+ * `mailwoman tiger redistricting` for each state you hold. Databases are never patched in place.
+ */
+async function assertPLBlockShape(db: Kysely<TIGERDatabase>): Promise<void> {
+	const columns = await sql<{ name: string }>`select name from pragma_table_info('pl_block')`.execute(db)
+	const names = new Set(columns.rows.map((row) => row.name))
+
+	for (const required of ["housing_units", "occupied", "vacant"]) {
+		if (!names.has(required)) {
+			throw new Error(
+				`pl_block predates its H1 columns (missing ${required}). It is a derived table: drop it and re-run \`mailwoman tiger redistricting\` for each state, which reloads P2 and H1 together.`
+			)
+		}
+	}
+}
+
 export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<void> {
 	await db.schema
 		.createTable("us_state")
@@ -177,11 +208,16 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 		.addColumn("nhpi", "integer", (c) => c.notNull())
 		.addColumn("other", "integer", (c) => c.notNull())
 		.addColumn("multi", "integer", (c) => c.notNull())
+		.addColumn("housing_units", "integer", (c) => c.notNull())
+		.addColumn("occupied", "integer", (c) => c.notNull())
+		.addColumn("vacant", "integer", (c) => c.notNull())
 		// pl_block is small (no geometry) and always probed by its GEOID PK (1:1 join to tabblock20), so
 		// cluster it WITHOUT ROWID — one B-tree probe per join, no separate rowid + PK-index pair.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 
+	await assertPLBlockShape(db)
+
 	await db.schema
 		.createTable("tiger_streets")
 		.ifNotExists()

package/{sdk → lib/sdk}/state/TIGERTabulatedBlockEntity.ts

@@ -5,7 +5,8 @@
  */
 
 import { smartSnakeCase } from "@mailwoman/core"
-import { TIGERProperty } from "@mailwoman/tiger"
+
+import { TIGERProperty } from "#index"
 
 /**
  * Default column selections for TIGER tabulated block entities.

package/{sdk → lib/sdk}/state/TIGERTractEntity.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { AdminLevel1Code, FIPSCountyCode, FIPSTractCode } from "@mailwoman/tiger"
+import type { AdminLevel1Code, FIPSCountyCode, FIPSTractCode } from "#index"
 
 /**
  * @internal

package/{sdk → lib/sdk}/state/block-operations.ts

@@ -5,7 +5,8 @@
  */
 
 import type { GeometryLiteral, MultiPolygonLiteral } from "@mailwoman/spatial"
-import { wellKnownGeometryToGeoJSON } from "@mailwoman/spatial/sdk"
+import { wellKnownGeometryToGeoJSON } from "@mailwoman/spatial/well-known-text"
+
 import type {
 	FIPSStateCode,
 	FIPSBlockGeoID,
@@ -13,7 +14,7 @@ import type {
 	TIGERBlockFeature,
 	TIGERBlockFeatureCollection,
 	TIGERTabulatedBlockProperties,
-} from "@mailwoman/tiger"
+} from "#index"
 
 export interface StateBlockIntersectionCriteria {
 	stateCode: FIPSStateCode

package/lib/sdk/state/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#sdk/state/block-operations"
+export * from "#sdk/state/TIGERTabulatedBlockEntity"
+export * from "#sdk/state/TIGERTractEntity"

package/{state.ts → lib/state.ts}

@@ -6,8 +6,8 @@
 
 import type { GeoFeature, MultiPolygonLiteral } from "@mailwoman/spatial"
 
-import type { GeoIDPart } from "./geoid.ts"
-import type { TIGERTabulatedBlockProperties } from "./tabulation-block.ts"
+import type { GeoIDPart } from "#geoid"
+import type { TIGERTabulatedBlockProperties } from "#tabulation-block"
 
 //#region FIPS Codes
 

package/{tabulation-block.ts → lib/tabulation-block.ts}

@@ -6,8 +6,8 @@
 
 import type { MultiPolygonLiteral } from "@mailwoman/spatial"
 
-import type { TIGERProperty, TIGERPropertyRecord } from "./constants.ts"
-import type { GeoIDPart, FIPSBlockGeoID, ParsedGeoIDBlockLevel } from "./geoid.ts"
+import type { TIGERProperty, TIGERPropertyRecord } from "#constants"
+import type { GeoIDPart, FIPSBlockGeoID, ParsedGeoIDBlockLevel } from "#geoid"
 
 /**
  * The properties of a tabulated block from the TIGER/Line dataset.