austrata 0.1.0__tar.gz

austrata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sia Ghelichkhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

austrata-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: austrata
+Version: 0.1.0
+Summary: Access Geoscience Australia borehole and hydrogeology data with a provenance-aware local cache
+Author-email: Sia Ghelichkhan <siavash.ghelichkhan@anu.edu.au>
+License: MIT
+Project-URL: Repository, https://github.com/g-adopt/austrata
+Project-URL: Issues, https://github.com/g-adopt/austrata/issues
+Keywords: geoscience australia,boreholes,hydrogeology,stratigraphy,geospatial
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geopandas>=0.14
+Requires-Dist: shapely>=2.0
+Requires-Dist: pyproj>=3.5
+Requires-Dist: pyogrio>=0.7
+Requires-Dist: fiona>=1.9
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: requests>=2.28
+Requires-Dist: tenacity>=8.2
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: filelock>=3.12
+Requires-Dist: tqdm>=4.64
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0; extra == "dev"
+Requires-Dist: vcrpy>=5.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: flake8>=5.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: mypy>=0.990; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Dynamic: license-file
+
+# austrata
+
+[![Tests](https://github.com/g-adopt/austrata/actions/workflows/tests.yml/badge.svg)](https://github.com/g-adopt/austrata/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/austrata.svg)](https://pypi.org/project/austrata/)
+[![Python](https://img.shields.io/pypi/pyversions/austrata.svg)](https://pypi.org/project/austrata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Access Geoscience Australia borehole and hydrogeology data through their open
+OGC/ArcGIS web services, with a provenance-aware local cache.
+
+`austrata` models boreholes as first-class objects (a header plus downhole
+stratigraphy and earth-material logs), lets you pull every bore inside an
+arbitrary polygon or bounding box, and exposes the Hydrogeology of Australia
+polygon layer to overlay. It talks to two backends behind one API: the GA
+boreholes GeoServer (WFS) and the Hydrogeology of Australia ArcGIS MapServer.
+Results are cached locally as GeoParquet with a provenance manifest, and
+revalidated before refetching so repeated queries are cheap and reproducible.
+
+Everything is returned in lon/lat (EPSG:4283, GDA94 geographic). Map projection
+and mesh generation are deliberately out of scope — those live in the companion
+`omega` package, which consumes this one.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.11+. Runtime dependencies are geopandas, shapely, pyproj,
+pyogrio, pyarrow, requests, tenacity, platformdirs, and filelock.
+
+## Quickstart
+
+```python
+from austrata import GADataClient
+from shapely.geometry import box
+
+ga = GADataClient()                      # cache defaults to the OS user cache dir
+
+# Boreholes inside a bounding box (lon/lat). Paginated and cached automatically.
+bores = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1))
+print(len(bores), "boreholes")
+gdf = bores.to_geodataframe()            # headers as a GeoDataFrame (EPSG:4283)
+
+# Or pass any shapely geometry as the region.
+bores = ga.boreholes(region=box(148.9, -35.6, 149.3, -35.1))
+
+# Load downhole logs for the whole collection in one shot (ENO-batched, cached).
+bores.load_logs("stratigraphy")
+for b in bores:
+    for interval in b.stratigraphy:      # list of StratigraphyInterval
+        if interval.valid:
+            print(b.name, interval.top_depth, interval.bottom_depth, interval.unit)
+
+bores.load_logs("earth_material")        # b.earth_material is then populated
+
+# Export the loaded logs as a tidy GeoDataFrame (one row per interval, borehole
+# point geometry, EPSG:4283). Save with geopandas: .to_file('x.gpkg') / .to_csv(...).
+strat = bores.stratigraphy_geodataframe()
+earth = bores.earth_material_geodataframe()
+
+# A single borehole by ENO or PID.
+one = ga.borehole("35147")
+
+# Hydrogeology polygons to overlay, as a GeoDataFrame.
+hydro = ga.hydrogeology(bbox=(148.9, -35.6, 149.3, -35.1))
+
+# A backend filter passes straight through.
+diamond = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1), filter="drillingMethod='Diamond'")
+```
+
+### Dry-run counts
+
+Pass `count_only=True` to get the number of features without downloading them
+(uses the cheap `resultType=hits` / `returnCountOnly` paths):
+
+```python
+n_bores = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1), count_only=True)
+n_units = ga.hydrogeology(bbox=(148.9, -35.6, 149.3, -35.1), count_only=True)
+```
+
+### Caching, freshness, and offline use
+
+Each logical query is cached as a `<hash>.parquet` file plus an entry in a
+`manifest.json`, in an OS-appropriate user cache directory
+(e.g. `~/Library/Caches/austrata` on macOS). Override the location with the
+`cache_dir=` argument or the `AUSTRATA_DATA_DIR` environment variable.
+
+On a repeat query `austrata` revalidates rather than blindly refetching: the
+ArcGIS path uses the service `ETag` (conditional `If-None-Match`), and the WFS
+path — which exposes no ETag — compares the `numberMatched` count as a cheap
+fingerprint. Both fall back to a max-age TTL (30 days by default), so a
+same-count content edit is eventually picked up. `force_refresh=True` is the
+only hard guarantee of a fresh pull.
+
+```python
+ga = GADataClient(offline=True)          # never touch the network; serve cache or raise
+ga = GADataClient(max_age=7 * 24 * 3600) # revalidate-by-refetch weekly
+bores = ga.boreholes(bbox=..., force_refresh=True)
+
+# Inspect or clear the cache.
+ga.cache.info()                          # dir, entry count, total bytes, per-entry detail
+ga.cache.list()                          # cached keys
+ga.cache.clear()                         # wipe everything (or clear(key) for one)
+```
+
+To prefetch for offline/field use, run the queries you need once while online;
+they land in the cache and an `offline=True` client serves them thereafter.
+
+### Citing the data
+
+Geoscience Australia publishes this data under CC BY 4.0. `austrata` records the
+provenance of every cached query so you can cite it with its access date:
+
+```python
+print(bores.citation())                  # citation string incl. "Accessed YYYY-MM-DD"
+bores.provenance()                        # dict: source_url, license, fetched_at, ...
+
+from austrata import hydrogeology_citation
+print(hydrogeology_citation(hydro))
+```
+
+## The lon/lat (GDA94) contract
+
+Both services are native EPSG:4283 (GDA94 geographic). `austrata` pins this end to
+end: the WFS bbox carries an explicit `EPSG:4283` suffix, and ArcGIS queries
+force `outSR=4283` (its GeoJSON otherwise silently defaults to WGS84). Every
+geometry you get back is lon/lat in GDA94 — no reprojection happens here.
+
+## Architecture
+
+The package follows clean-architecture / DDD layering (see `DESIGN.md`):
+
+- `domain/` — pure value objects and entities (`Region`, `Borehole`,
+  `BoreholeCollection`, `StratigraphyInterval`, `EarthMaterialInterval`,
+  `HydrogeologyUnit`). No I/O.
+- `ports/` — the interfaces the application layer depends on (`BoreholeSource`,
+  `HydrogeologySource`, `DatasetCache`).
+- `application/` — use cases that build per-backend cache fetch-plans.
+- `infrastructure/` — the HTTP client, the WFS and ArcGIS adapters, the feature
+  mappers, and the dataset cache.
+- `client.py` — the `GADataClient` facade that wires it together.
+
+## License
+
+MIT (the code). The data accessed through it is © Geoscience Australia, CC BY 4.0.

austrata-0.1.0/README.md

@@ -0,0 +1,146 @@
+# austrata
+
+[![Tests](https://github.com/g-adopt/austrata/actions/workflows/tests.yml/badge.svg)](https://github.com/g-adopt/austrata/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/austrata.svg)](https://pypi.org/project/austrata/)
+[![Python](https://img.shields.io/pypi/pyversions/austrata.svg)](https://pypi.org/project/austrata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Access Geoscience Australia borehole and hydrogeology data through their open
+OGC/ArcGIS web services, with a provenance-aware local cache.
+
+`austrata` models boreholes as first-class objects (a header plus downhole
+stratigraphy and earth-material logs), lets you pull every bore inside an
+arbitrary polygon or bounding box, and exposes the Hydrogeology of Australia
+polygon layer to overlay. It talks to two backends behind one API: the GA
+boreholes GeoServer (WFS) and the Hydrogeology of Australia ArcGIS MapServer.
+Results are cached locally as GeoParquet with a provenance manifest, and
+revalidated before refetching so repeated queries are cheap and reproducible.
+
+Everything is returned in lon/lat (EPSG:4283, GDA94 geographic). Map projection
+and mesh generation are deliberately out of scope — those live in the companion
+`omega` package, which consumes this one.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.11+. Runtime dependencies are geopandas, shapely, pyproj,
+pyogrio, pyarrow, requests, tenacity, platformdirs, and filelock.
+
+## Quickstart
+
+```python
+from austrata import GADataClient
+from shapely.geometry import box
+
+ga = GADataClient()                      # cache defaults to the OS user cache dir
+
+# Boreholes inside a bounding box (lon/lat). Paginated and cached automatically.
+bores = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1))
+print(len(bores), "boreholes")
+gdf = bores.to_geodataframe()            # headers as a GeoDataFrame (EPSG:4283)
+
+# Or pass any shapely geometry as the region.
+bores = ga.boreholes(region=box(148.9, -35.6, 149.3, -35.1))
+
+# Load downhole logs for the whole collection in one shot (ENO-batched, cached).
+bores.load_logs("stratigraphy")
+for b in bores:
+    for interval in b.stratigraphy:      # list of StratigraphyInterval
+        if interval.valid:
+            print(b.name, interval.top_depth, interval.bottom_depth, interval.unit)
+
+bores.load_logs("earth_material")        # b.earth_material is then populated
+
+# Export the loaded logs as a tidy GeoDataFrame (one row per interval, borehole
+# point geometry, EPSG:4283). Save with geopandas: .to_file('x.gpkg') / .to_csv(...).
+strat = bores.stratigraphy_geodataframe()
+earth = bores.earth_material_geodataframe()
+
+# A single borehole by ENO or PID.
+one = ga.borehole("35147")
+
+# Hydrogeology polygons to overlay, as a GeoDataFrame.
+hydro = ga.hydrogeology(bbox=(148.9, -35.6, 149.3, -35.1))
+
+# A backend filter passes straight through.
+diamond = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1), filter="drillingMethod='Diamond'")
+```
+
+### Dry-run counts
+
+Pass `count_only=True` to get the number of features without downloading them
+(uses the cheap `resultType=hits` / `returnCountOnly` paths):
+
+```python
+n_bores = ga.boreholes(bbox=(148.9, -35.6, 149.3, -35.1), count_only=True)
+n_units = ga.hydrogeology(bbox=(148.9, -35.6, 149.3, -35.1), count_only=True)
+```
+
+### Caching, freshness, and offline use
+
+Each logical query is cached as a `<hash>.parquet` file plus an entry in a
+`manifest.json`, in an OS-appropriate user cache directory
+(e.g. `~/Library/Caches/austrata` on macOS). Override the location with the
+`cache_dir=` argument or the `AUSTRATA_DATA_DIR` environment variable.
+
+On a repeat query `austrata` revalidates rather than blindly refetching: the
+ArcGIS path uses the service `ETag` (conditional `If-None-Match`), and the WFS
+path — which exposes no ETag — compares the `numberMatched` count as a cheap
+fingerprint. Both fall back to a max-age TTL (30 days by default), so a
+same-count content edit is eventually picked up. `force_refresh=True` is the
+only hard guarantee of a fresh pull.
+
+```python
+ga = GADataClient(offline=True)          # never touch the network; serve cache or raise
+ga = GADataClient(max_age=7 * 24 * 3600) # revalidate-by-refetch weekly
+bores = ga.boreholes(bbox=..., force_refresh=True)
+
+# Inspect or clear the cache.
+ga.cache.info()                          # dir, entry count, total bytes, per-entry detail
+ga.cache.list()                          # cached keys
+ga.cache.clear()                         # wipe everything (or clear(key) for one)
+```
+
+To prefetch for offline/field use, run the queries you need once while online;
+they land in the cache and an `offline=True` client serves them thereafter.
+
+### Citing the data
+
+Geoscience Australia publishes this data under CC BY 4.0. `austrata` records the
+provenance of every cached query so you can cite it with its access date:
+
+```python
+print(bores.citation())                  # citation string incl. "Accessed YYYY-MM-DD"
+bores.provenance()                        # dict: source_url, license, fetched_at, ...
+
+from austrata import hydrogeology_citation
+print(hydrogeology_citation(hydro))
+```
+
+## The lon/lat (GDA94) contract
+
+Both services are native EPSG:4283 (GDA94 geographic). `austrata` pins this end to
+end: the WFS bbox carries an explicit `EPSG:4283` suffix, and ArcGIS queries
+force `outSR=4283` (its GeoJSON otherwise silently defaults to WGS84). Every
+geometry you get back is lon/lat in GDA94 — no reprojection happens here.
+
+## Architecture
+
+The package follows clean-architecture / DDD layering (see `DESIGN.md`):
+
+- `domain/` — pure value objects and entities (`Region`, `Borehole`,
+  `BoreholeCollection`, `StratigraphyInterval`, `EarthMaterialInterval`,
+  `HydrogeologyUnit`). No I/O.
+- `ports/` — the interfaces the application layer depends on (`BoreholeSource`,
+  `HydrogeologySource`, `DatasetCache`).
+- `application/` — use cases that build per-backend cache fetch-plans.
+- `infrastructure/` — the HTTP client, the WFS and ArcGIS adapters, the feature
+  mappers, and the dataset cache.
+- `client.py` — the `GADataClient` facade that wires it together.
+
+## License
+
+MIT (the code). The data accessed through it is © Geoscience Australia, CC BY 4.0.

austrata-0.1.0/austrata/__init__.py

@@ -0,0 +1,43 @@
+"""austrata — Geoscience Australia borehole and hydrogeology data access.
+
+The main entry point is :class:`GADataClient`. The domain value objects are
+exported too for callers that want to work with the typed model directly.
+"""
+import logging as _logging
+
+# Structured logging lives under the "austrata" namespace and is silent by
+# default (a NullHandler), per library best practice. Applications opt in via
+# logging.getLogger("austrata").setLevel(...) and attach their own handler.
+# Configured before submodule imports so their module-level getLogger calls
+# inherit a silenced parent regardless of import order.
+_logging.getLogger("austrata").addHandler(_logging.NullHandler())
+
+from austrata.domain.region import Region  # noqa: E402
+from austrata.domain.borehole import Borehole, BoreholeCollection  # noqa: E402
+from austrata.domain.stratigraphy import StratigraphyInterval, EarthMaterialInterval  # noqa: E402
+from austrata.domain.construction import ConstructionInterval  # noqa: E402
+from austrata.domain.hydrogeology import HydrogeologyUnit  # noqa: E402
+from austrata.client import (  # noqa: E402
+    GADataClient,
+    hydrogeology_citation,
+    hydrogeology_provenance,
+)
+from austrata.ngis_client import NGISClient  # noqa: E402
+from austrata.groundwater_client import GroundwaterClient  # noqa: E402
+
+__all__ = [
+    "GADataClient",
+    "NGISClient",
+    "GroundwaterClient",
+    "Region",
+    "Borehole",
+    "BoreholeCollection",
+    "StratigraphyInterval",
+    "EarthMaterialInterval",
+    "ConstructionInterval",
+    "HydrogeologyUnit",
+    "hydrogeology_provenance",
+    "hydrogeology_citation",
+]
+
+__version__ = "0.1.0"

austrata-0.1.0/austrata/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer: use cases orchestrating ports. Filled in a later task."""

austrata-0.1.0/austrata/application/fetch_boreholes.py

@@ -0,0 +1,119 @@
+"""Use case: build the cache fetch-plan for borehole headers (WFS).
+
+The WFS backend emits no ETag/Last-Modified, so freshness uses the cheap
+``resultType=hits`` ``numberMatched`` count as a server fingerprint, ANDed with
+the cache's max-age TTL backstop (a same-count content edit is undetectable by
+count alone — documented best-effort, ``force_refresh`` is the only guarantee).
+
+This module knows the *strategy* (fingerprint by count, no conditional headers)
+but not HTTP detail — it composes a :class:`FetchPlan` from the injected
+``BoreholeSource`` adapter.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from austrata.domain.region import Region
+from austrata.infrastructure.dataset_cache import FetchPlan
+from austrata.infrastructure.feature_mapper import borehole_features_to_gdf
+from austrata.ports.data_source import BoreholeSource
+
+WFS_SERVICE = "ga-boreholes-wfs"
+WFS_LAYER = "gsmlp:BoreholeView"
+WFS_CITATION = (
+    "Geoscience Australia Borehole Database, accessed via the GA Boreholes "
+    "WFS (gsmlp:BoreholeView)."
+)
+WFS_LICENSE = "CC BY 4.0"
+WFS_SOURCE_URL = "https://services.ga.gov.au/gis/boreholes/wfs"
+WFS_SERVICE_VERSION = "WFS 2.0.0"
+
+
+def header_cache_key(region: Region, cql_filter: Optional[str]) -> str:
+    """Stable cache key for a headers query: region geometry + layer + filter."""
+    descriptor = f"{WFS_SERVICE}|{WFS_LAYER}|{cql_filter or ''}"
+    return f"{region.cache_key()}-{_short_hash(descriptor)}"
+
+
+def build_header_plan(
+    source: BoreholeSource, region: Region, cql_filter: Optional[str]
+) -> FetchPlan:
+    """Compose the FetchPlan the cache uses to fetch/revalidate headers."""
+
+    def fingerprint(_stored: dict) -> dict:
+        # WFS fingerprint is the live count; it does not depend on the stored
+        # entry (``_stored``), unlike the ArcGIS etag probe.
+        return {"server_fingerprint": {"numberMatched": source.count_headers(region, cql_filter)}}
+
+    def unchanged(stored: dict, current: dict) -> bool:
+        return stored.get("server_fingerprint") == current.get("server_fingerprint")
+
+    def fetch():
+        features = source.fetch_headers(region, cql_filter)
+        gdf = borehole_features_to_gdf(features)
+        provenance_extra = {
+            "server_fingerprint": {"numberMatched": len(features)},
+            "citation": WFS_CITATION,
+            "license": WFS_LICENSE,
+            "source_url": WFS_SOURCE_URL,
+            "service_version": WFS_SERVICE_VERSION,
+        }
+        return gdf, provenance_extra
+
+    return FetchPlan(
+        fetch_fn=fetch,
+        fingerprint_fn=fingerprint,
+        unchanged_fn=unchanged,
+        query={
+            "service": WFS_SERVICE,
+            "layer": WFS_LAYER,
+            "region_wkt": region.geometry.wkt,
+            "filter": cql_filter,
+        },
+    )
+
+
+def log_cache_key(kind: str, enos) -> str:
+    """Stable cache key for a log pull, keyed by kind + the sorted ENO set."""
+    unique = sorted({int(e) for e in enos})
+    descriptor = f"{WFS_SERVICE}|logs|{kind}|{','.join(map(str, unique))}"
+    return f"logs-{kind}-{_short_hash(descriptor)}"
+
+
+def build_log_plan(source: BoreholeSource, kind: str, enos) -> FetchPlan:
+    """Compose a FetchPlan for an ENO-set log pull (stratigraphy/earth-material).
+
+    Logs for a fixed ENO set are content-stable enough that freshness leans on
+    the TTL backstop; no cheap per-ENO fingerprint exists, so no fingerprint_fn
+    is supplied (the cache then revalidates purely by max-age).
+    """
+    from austrata.infrastructure.feature_mapper import log_features_to_dataframe
+
+    unique = sorted({int(e) for e in enos})
+
+    def fetch():
+        if kind == "stratigraphy":
+            features = source.fetch_stratigraphy(unique)
+        elif kind == "earth_material":
+            features = source.fetch_earth_material(unique)
+        else:
+            raise ValueError(f"Unknown log kind {kind!r}.")
+        df = log_features_to_dataframe(features)
+        provenance_extra = {
+            "citation": WFS_CITATION,
+            "license": WFS_LICENSE,
+            "source_url": WFS_SOURCE_URL,
+            "service_version": WFS_SERVICE_VERSION,
+        }
+        return df, provenance_extra
+
+    return FetchPlan(
+        fetch_fn=fetch,
+        query={"service": WFS_SERVICE, "layer": f"logs:{kind}", "enos": unique},
+    )
+
+
+def _short_hash(text: str) -> str:
+    import hashlib
+
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]

austrata-0.1.0/austrata/application/fetch_hydrogeology.py

@@ -0,0 +1,93 @@
+"""Use case: build the cache fetch-plan for hydrogeology polygons (ArcGIS).
+
+The ArcGIS backend emits an ETag, so freshness uses a conditional probe: send
+``If-None-Match`` with the stored etag and treat a 304 as fresh. The probe is a
+cheap ``returnCountOnly`` query the adapter owns (``probe_etag``), so this module
+stays HTTP-free and the cache stays backend-agnostic.
+"""
+from __future__ import annotations
+
+from typing import Optional, Protocol
+
+from austrata.domain.region import Region
+from austrata.infrastructure.dataset_cache import FetchPlan
+from austrata.infrastructure.feature_mapper import hydrogeology_features_to_gdf
+
+ARCGIS_SERVICE = "ga-hydrogeology-arcgis"
+ARCGIS_LAYER = "Hydrogeology_of_Australia/0"
+ARCGIS_CITATION = (
+    "Hydrogeology of Australia, Geoscience Australia, accessed via the "
+    "Hydrogeology_of_Australia ArcGIS MapServer (layer 0)."
+)
+ARCGIS_LICENSE = "CC BY 4.0"
+ARCGIS_SOURCE_URL = (
+    "https://services.ga.gov.au/gis/rest/services/"
+    "Hydrogeology_of_Australia/MapServer"
+)
+ARCGIS_SERVICE_VERSION = "ArcGIS REST MapServer"
+
+
+class HydrogeologyProbeSource(Protocol):
+    """The hydrogeology source plus the conditional ETag probe this plan needs."""
+
+    def fetch_units(self, region: Region, where: Optional[str] = None) -> list: ...
+    def probe_etag(self, region: Region, where: Optional[str] = None,
+                   etag: Optional[str] = None) -> dict: ...
+
+
+def hydrogeology_cache_key(region: Region, where: Optional[str]) -> str:
+    """Stable cache key for a hydrogeology query: region + layer + where."""
+    descriptor = f"{ARCGIS_SERVICE}|{ARCGIS_LAYER}|{where or ''}"
+    return f"{region.cache_key()}-{_short_hash(descriptor)}"
+
+
+def build_hydrogeology_plan(
+    source: HydrogeologyProbeSource, region: Region, where: Optional[str]
+) -> FetchPlan:
+    """Compose the FetchPlan the cache uses to fetch/revalidate hydrogeology."""
+
+    def conditional_headers(stored: dict) -> dict:
+        etag = stored.get("etag")
+        return {"If-None-Match": etag} if etag else {}
+
+    def fingerprint(stored: dict) -> dict:
+        # A 304 here proves freshness; otherwise we carry the new etag forward.
+        return source.probe_etag(region, where, etag=stored.get("etag"))
+
+    def unchanged(stored: dict, current: dict) -> bool:
+        if current.get("not_modified"):
+            return True
+        cur_etag = current.get("etag")
+        return cur_etag is not None and cur_etag == stored.get("etag")
+
+    def fetch():
+        features = source.fetch_units(region, where)
+        gdf = hydrogeology_features_to_gdf(features)
+        probe = source.probe_etag(region, where)
+        provenance_extra = {
+            "etag": probe.get("etag"),
+            "citation": ARCGIS_CITATION,
+            "license": ARCGIS_LICENSE,
+            "source_url": ARCGIS_SOURCE_URL,
+            "service_version": ARCGIS_SERVICE_VERSION,
+        }
+        return gdf, provenance_extra
+
+    return FetchPlan(
+        fetch_fn=fetch,
+        fingerprint_fn=fingerprint,
+        unchanged_fn=unchanged,
+        conditional_headers_fn=conditional_headers,
+        query={
+            "service": ARCGIS_SERVICE,
+            "layer": ARCGIS_LAYER,
+            "region_wkt": region.geometry.wkt,
+            "filter": where,
+        },
+    )
+
+
+def _short_hash(text: str) -> str:
+    import hashlib
+
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]