Measure FRAP geometry validity and DINS coordinate validity as coverage fields

[ChelseaKR]

What

The build reads attribute rows and never the geometry column, yet the geometry is the field a perimeter dataset exists for. This adds geometry to the measured fields: for each FRAP record, whether a geometry is present, whether it is empty, whether it passes an OGC validity check, whether it is multipart, and whether its computed area agrees with GIS_ACRES within a stated tolerance; for each DINS record, whether latitude and longitude are present, numeric, and inside California's published extent. Each is published as a three-state field (recorded, recorded-as-unknown, empty) with counts, per year for FRAP and per incident for DINS, plus the count of records whose recorded acreage and computed area disagree.

Why it matters

A record with attributes and no polygon is incomplete in the way the project already counts, and an invalid polygon answers a spatial question undefined; the sibling wildfire-service-territory-overlap measured exactly that on the CEC layer (eight invalid outlines, two of them the largest) and had to repair before use. Nothing here repairs, draws, or republishes a shape or a coordinate; it counts. The acquisition pulls attributes only today, so acquire.py gains an explicit --with-geometry, and the artifacts record whether geometry was acquired, publishing null for these fields when it was not.

Scope

• acquire.py --with-geometry and a recorded geometry_acquired fact in acquisition.json and the artifacts.
• src/perimeter/geometry.py: validity via shapely (new pinned dependency), area in the projection FRAP publishes, tolerance declared in schema.py with its reason.
• Fields GEOMETRY_PRESENT, GEOMETRY_VALID, GEOMETRY_PARTS, AREA_AGREES_WITH_GIS_ACRES (FRAP) and COORDINATE_IN_EXTENT (DINS); page tables and docs/MARKERS.md entries.
• Fixtures gain a hand-written invalid polygon and an out-of-extent coordinate.

Out of scope

• Repairing geometry, publishing any shape, or spatial joins.
• Republishing any coordinate; only counts leave the build.

Done when

• Fixtures report the invalid polygon and the out-of-extent point in the expected buckets, and a build without geometry publishes null for every geometry field with geometry_acquired: false.
• A geometry column present but unreadable raises SchemaDriftError rather than counting as empty.
• The determinism gate holds with geometry included.

Pointers

• src/perimeter/acquire.py, records.py, schema.py (FieldSpec), artifacts.py
• wildfire-service-territory-overlap/src/wildfire_service_territory_overlap/geometry.py (validity ledger)

Proposed with AI assistance.

[ChelseaKR]

Triage against origin/main @ d4f533f (2026-09-06). Not built: no src/perimeter/geometry.py, no --with-geometry in acquire.py, no geometry_acquired fact.

Blocked on two things an agent should not decide alone.

1. A new pinned runtime dependency. pyproject.toml currently declares dependencies = [] — this project has no runtime dependencies, which is a posture, not an accident, and shapes make audit and the whole supply-chain story. Adding shapely is a real change to that posture and deserves an explicit yes.
2. A new acquisition. The current pinned retrieval pulled attributes only. Geometry means going back to CAL FIRE's endpoint for a much larger payload, and PROVENANCE.md treats a retrieval as a dated, hashed act performed by hand and never from a build. That is the maintainer's action.

What is right about the design and worth keeping when it is built: publishing null for every geometry field with geometry_acquired: false, rather than zero or absent. A build that did not acquire geometry and a build whose geometry was all invalid must not produce the same artifact. Likewise "a geometry column present but unreadable raises SchemaDriftError rather than counting as empty" — an unreadable column counted as empty is a failed read published as a measurement.

Automatable half, if split: geometry.py and its tests against hand-written fixture polygons (one invalid, one out-of-extent point), with --with-geometry implemented but nothing re-acquired and the artifacts publishing null. That gets the arithmetic under test and changes no published figure.

Needs from the owner: the dependency call, and a geometry retrieval.

Triaged with AI assistance.

[ChelseaKR]

Triage, 2026-09-07. Unbuilt, and half of it is blocked and half is not, which is worth knowing before someone starts.

• The DINS half is unblocked. LATITUDE and LONGITUDE are already acquired and already measured fields; the survey run over the pinned retrieval reports 131,567 and 131,965 distinct values, none empty. COORDINATE_IN_EXTENT needs no new acquisition.
• The FRAP half needs a new acquisition. data/raw/frap_perimeters.json was fetched without geometry (upstream's field lists deliberately exclude it, and a test holds that), so GEOMETRY_PRESENT, GEOMETRY_VALID, GEOMETRY_PARTS and AREA_AGREES_WITH_GIS_ACRES have nothing to read. That is acquire --with-geometry, a hand-run network step, plus a new pinned file and hash in PROVENANCE.md.

The issue already anticipates this correctly: it says the artifacts record geometry_acquired and publish null for the geometry fields when it is false, which is the right shape and is the reason the two halves can land separately. Splitting them into two issues would probably help, since one is a page-and-registry change and the other is a retrieval decision.

It also adds shapely as a runtime dependency, which this repository currently has none of.

Prepared with AI assistance; reviewed before submission.