Make acquire a reusable library: caller User-Agent, geometry, post-walk checks

[ChelseaKR]

What

perimeter.acquire is consumed by wildfire-service-territory-overlap, which pins a commit and on 2026-09-05 audited the seam, recording four gaps in its docs/UPSTREAM.md: the walk sends only perimeter's User-Agent, so CAL FIRE's logs cannot see who is calling; the paged walk cannot return geometry, so the consumer copied the offset loop; completeness is one record count read once before the walk, so the consumer added a post-walk recount and identifier ordering and uniqueness checks; and the package ships no py.typed, so a strict consumer carries two mypy overrides. This closes all four here so the consumer's compensations can be deleted: user_agent on layer_record_count and fetch_layer; geometry, format and spatial-reference arguments (or an exposed page iterator); a second count after the walk with strictly increasing unique identifiers as an acquisition guard; and src/perimeter/py.typed.

Why it matters

The relationship is "consume, do not re-implement", and every gap left open is a copied loop that will drift. Each change strengthens perimeter's own guarantee that a short download is not an acquisition (the post-walk count catches a truncated walk the pre-walk count cannot), and none touches the measurement or the pages. The network path stays hand-run and out of CI; tests substitute the socket as they do today.

Scope

• acquire.py: user_agent: str = USER_AGENT threaded through _get; fetch_layer(..., return_geometry=False, out_fields=..., out_sr=...) or iter_pages(...); post-walk recount and identifier checks that refuse to write on failure, recorded in acquisition.json.
• py.typed; pyproject.toml package data.
• A CHANGELOG entry naming the consumer's audit, so its docs/UPSTREAM.md rows become closable at the next pin.

Out of scope

• Changing what perimeter itself acquires by default.
• Publishing to PyPI under a new name (a separate decision; perimeter is taken).

Done when

• A test asserts the User-Agent a caller supplies is what _get sends, and the default still names this project.
• A simulated walk returning fewer records than the post-walk count refuses to write and names both counts; a walk with a repeated identifier refuses.
• mypy --strict over a minimal consumer importing perimeter.acquire passes with no overrides.
• Geometry requested through the library round-trips a fixture feature's coordinates unchanged.

Pointers

• src/perimeter/acquire.py, tests/test_acquire.py, pyproject.toml
• wildfire-service-territory-overlap/docs/UPSTREAM.md (audit of 2026-09-05 at dac60195), its acquire.py, and its issue Add an artifact diff command so a deliberate refresh is compared value by value #58

Proposed with AI assistance.

[ChelseaKR]

Triage against origin/main @ d4f533f (2026-09-06). All four gaps confirmed present:

• acquire.py:118 sends USER_AGENT unconditionally; layer_record_count (line 144) and fetch_layer (line 167) take no user_agent.
• fetch_layer(endpoint, fields) has no geometry, format or spatial-reference arguments and exposes no page iterator.
• Completeness is the one pre-walk count; there is no post-walk recount and no identifier ordering or uniqueness check.
• There is no src/perimeter/py.typed.

Automatable, and unusually well-specified because a real consumer wrote the audit. Nothing here needs a decision: the four items are named, the consumer's compensations are named, and the "Done when" rows are all mechanically checkable offline (the network path stays hand-run; tests substitute the socket as they do today).

The item worth building even if the others are dropped is the post-walk recount. A pre-walk count read once cannot see a walk that stopped early — that is a truncated dataset published as complete, which is this portfolio's most common defect, and the guard is cheap: count again after the walk, require strictly increasing unique identifiers, and refuse to write if either fails, recording both counts in acquisition.json.

One caution on the py.typed half: adding it makes this package's types a published interface for the consumer that pins it. That is the intent, and it means a later signature change becomes a breaking change for them. Worth stating in the CHANGELOG entry the issue already asks for.

Not started here. Nothing blocks it.

Triaged with AI assistance.

[ChelseaKR]

Shipped. This landed on main as #75 (feat/acquire-as-a-library), squash-merged at 89f1e73 — "Make acquire a library a second project can consume, and check the walk it hands back". The branch was left undeleted, which is why the issue looked unclaimed.

All four gaps from the consumer's docs/UPSTREAM.md audit are closed on origin/main:

1. Caller User-Agent — _get(url, *, user_agent=USER_AGENT), threaded through layer_record_count, iter_features, fetch_layer and acquire. Held by test_a_caller_can_say_who_it_is_and_that_is_what_is_sent, test_the_default_user_agent_still_names_this_project, test_the_user_agent_reaches_the_count_query_and_the_walk, and a blank one is refused rather than passed through.
2. Geometry — iter_features(..., return_geometry=False, out_sr=None) is the exposed page iterator; test_geometry_requested_through_the_library_round_trips_unchanged is the round-trip check this asked for, and test_the_fetch_field_lists_do_not_ask_for_geometry holds the default unchanged.
3. Post-walk checks — a second layer_record_count after the walk plus identifier_failure, both refusing to write: test_a_walk_shorter_than_the_post_walk_count_is_refused_naming_both, test_a_layer_republished_mid_walk_is_refused_naming_both_counts, test_a_repeated_identifier_is_refused_even_though_the_count_matches, and test_every_identifier_refusal_is_reachable. test_the_manifest_records_which_guards_this_acquisition_passed records them in acquisition.json.
4. py.typed — src/perimeter/py.typed is committed and packaged via [tool.hatch.build.targets.wheel]; test_a_strict_consumer_needs_no_override_to_import_this_package is the mypy --strict consumer check.

The out-of-scope line held: what perimeter acquires by default did not change, and nothing was published to any index.

The sibling's docs/UPSTREAM.md rows become closable at its next pin — that follow-up is tracked in wildfire-service-territory-overlap, not here.

Closing as delivered.

Prepared with AI assistance; reviewed before submission.