Make acquire a library a second project can consume, and check the walk it hands back

[ChelseaKR]

Delivers every item listed in issue #64. Leaving that issue open for the owner to check off; nothing here needs her before it lands.

What was wrong

wildfire-service-territory-overlap pins a commit of this package and audited the seam on 2026-09-05, recording four gaps in its docs/UPSTREAM.md. All four are confirmed present on main and closed here, so the consumer's compensations can be deleted at its next pin.

Gap	On main before this
The walk sends only this project's User-Agent	acquire.py:118 sends USER_AGENT unconditionally; neither layer_record_count nor fetch_layer takes one
The paged walk cannot return geometry, so the consumer copied the offset loop	fetch_layer(endpoint, fields) — no geometry, no format, no spatial reference, no page iterator
Completeness is one record count read once before the walk	no post-walk recount, no identifier checks
No py.typed, so a strict consumer carries two mypy overrides	absent

What changed

A caller can say who it is. user_agent on _get, layer_record_count, fetch_layer and acquire, defaulting to this project's. An operator reading CAL FIRE's logs saw perimeter-coverage for requests a different project made — the header identified the library rather than the caller, which is the one thing a User-Agent exists to do.

A blank User-Agent is refused rather than passed through. urllib would substitute its own Python-urllib/3.x, so the request still goes out under a header naming no project at all: an absent identity sent as though it were one.

iter_features exposes the paged walk, with return_geometry and out_sr. The whole value of that loop is one rule — step by the page that arrived, not the page that was asked for, because a layer capping a page below PAGE_SIZE and setting exceededTransferLimit leaves a block of records between the end of this page and the next offset, and stepping by PAGE_SIZE walks over them while the walk still ends normally. A copy of that rule in another repository drifts.

A feature is yielded whole, not merged into its attributes: a layer is free to publish a field called geometry, and a merge would overwrite it silently — a loss that looks exactly like a layer that never published the field. There is a test for that case.

The default request is unchanged byte for byte (returnGeometry=false, and outSR absent rather than defaulted), because the raw files pinned in sources.py must stay reproducible.

The layer's total is read twice, before the walk and after it. One count read before a walk cannot see a layer republished while the walk was running: the walk ends at a total matching the number the layer held an hour ago, the pre-walk check passes, and a file assembled across two versions of a layer lands on disk with a clean hash and a date beside it. Two counts that disagree say exactly that, and the refusal names both.

The identifiers are checked, because a count that matches is not evidence that the right records were collected. The walk asks for OBJECTID ASC and steps an offset through the answer. A page handed back twice, or a result reordered under a concurrent edit, leaves the count intact and the contents wrong — some records collected twice and others not at all. identifier_failure refuses a repeat, a value that goes backwards, and a non-integer. True is in the test table on purpose: it is an int in Python and would slip past an isinstance(value, int) check written without the guard.

Ordering on a field and then never checking the order is a check that cannot fail, which is what main had.

acquisition.json records which guards this acquisition passed, not which ones the code contains. A manifest written before the post-walk recount existed and one written after it were otherwise indistinguishable, and a file that passed the recount is a different claim from a file that did not.

src/perimeter/py.typed, plus artifacts in the wheel target so it ships. This makes the annotations a published interface for the project that pins this one: a later signature change becomes a breaking change for them, which is the intent and is stated in the CHANGELOG.

Done-when, checked

From the issue	Result
A test asserts the User-Agent a caller supplies is what _get sends, and the default still names this project	both, plus a test that it is threaded into the count query and the walk rather than merely accepted
A simulated walk returning fewer records than the post-walk count refuses to write and names both counts	yes, and separately for a layer republished mid-walk, naming 3 records before the walk / 4 after it
A walk with a repeated identifier refuses	yes, with the message stating that a matching count is not evidence
mypy --strict over a minimal consumer importing perimeter.acquire passes with no overrides	yes — run as a subprocess in the test, not asserted from the file's existence
Geometry requested through the library round-trips a fixture feature's coordinates unchanged	yes, compared as the exact object the service sent

How it was verified

843 passed, coverage 100.00% total with branch coverage on (floor 90), acquire.py at 100% statements and 100% branches. mypy --strict clean over 12 source files. ruff check / ruff format --check clean. uv lock --check clean.

Five negative controls, each with the sabotage asserted present in the file before the result was read, and each restored from a byte copy whose SHA-256 was compared afterwards:

Sabotage	Asserted in file	Result
src/perimeter/py.typed deleted	ls reported it absent	mypy consumer test FAILED with missing library stubs or py.typed marker
post-walk recount removed (after = before)	grep -n showed the replacement line	…republished_mid_walk… FAILED, DID NOT RAISE
identifier_failure returns None immediately	grep -n showed the early return None	7 tests FAILED
_get sends USER_AGENT instead of the caller's	grep -n showed USER_AGENT in the header	…say_who_it_is… FAILED, positive control still passed
returnGeometry hard-coded to "false"	grep -n showed the literal	geometry round-trip FAILED

Restored, 55 passed in tests/test_acquire.py.

Note on the existing tests

The fakes in tests/test_acquire.py took _get(url) positionally, so they now accept **_. That is the only change to existing test bodies; no assertion was altered or removed. The autouse fixture that refuses a real socket is untouched and still enforces that nothing here contacts CAL FIRE.

Out of scope, as the issue says

Changing what this project acquires by default — nothing in sources.py, no re-acquisition, no published figure moves. And publishing to PyPI under a new name, which is a separate decision.

Prepared with AI assistance; reviewed before submission.