feat: re-instate hex tileset metadata.json tile-host route (un-revert #287) (#316) (#317)

Un-reverts #287, restoring the GET /tiles/{namespace}/{name}/metadata.json
route added in #255. The transcription-leak defense the route provides is
no longer a one-time qwen3 event (z-ai/glm-5.2 leaked its XML arg-dialect
into value_stats on ca-30x30, 2026-07-14), and geo-agent#276 now makes the
client fetch value_stats/bounds by hash from this route instead of routing
the JSON through the LLM's tool-call args -- resolving the 'no consumer'
objection. Restores serve_metadata, the route mount, and the
TestServeMetadata suite.

Author: cboettig

server.py

@@ -382,7 +382,7 @@ async def _query_tool(
 import concurrent.futures
 import threading
 import time
-from tiles.endpoint import serve_tile
+from tiles.endpoint import serve_metadata, serve_tile
 from tiles.db import build_tile_connection
 from tiles.pyramid import (
     MVT_LAYER_NAME,
@@ -869,6 +869,9 @@ def mount_tiles(app):
     con = _get_tile_con()
     app.state.tile_con = con
     app.add_route("/tiles/{namespace}/{name}/{z:int}/{x:int}/{y:int}.pbf", serve_tile)
+    # Same-origin metadata sidecar so clients can read value_stats/bounds by
+    # hash instead of routing the large JSON through an LLM's tool-call args.
+    app.add_route("/tiles/{namespace}/{name}/metadata.json", serve_metadata, methods=["GET"])
 
 # -------------------------------------------------------------------------
 # 9. OPTIONAL BEARER TOKEN AUTH

tests/test_tile_endpoint.py

@@ -5,7 +5,7 @@
 from starlette.routing import Route
 from starlette.testclient import TestClient
 
-from tiles.endpoint import serve_tile
+from tiles.endpoint import serve_metadata, serve_tile
 from tiles.pyramid import register_hex_tiles
 from tiles.db import build_tile_connection
 
@@ -25,6 +25,7 @@ def app_with_tiles(local_bucket):
     con = build_tile_connection()
     app = Starlette(routes=[
         Route("/tiles/{namespace}/{name}/{z:int}/{x:int}/{y:int}.pbf", serve_tile),
+        Route("/tiles/{namespace}/{name}/metadata.json", serve_metadata, methods=["GET"]),
     ])
     app.state.tile_con = con
     yield app
@@ -310,3 +311,48 @@ def test_endpoint_reads_finest_res_from_metadata(self, app_with_tiles, local_buc
         y = int((1 - math.log(math.tan(lat_rad) + 1/math.cos(lat_rad)) / math.pi) / 2 * n)
         r = client.get(f"/tiles/hex/{result['hash']}/{z}/{x}/{y}.pbf")
         assert r.status_code in (200, 204)  # not 404
+
+
+class TestServeMetadata:
+    """The /tiles/hex/<hash>/metadata.json sidecar route. Clients fetch
+    value_stats/bounds by hash here instead of transcribing them through an
+    LLM's tool-call args (weak models corrupt the large JSON → silent
+    no-op layer-add). See the hex-not-showing investigation."""
+
+    def test_returns_metadata_json_with_value_stats_and_bounds(self, app_with_tiles, registered_ca):
+        client = TestClient(app_with_tiles)
+        r = client.get(f"/tiles/hex/{registered_ca}/metadata.json")
+        assert r.status_code == 200
+        assert r.headers["content-type"].startswith("application/json")
+        meta = r.json()
+        # The exact fields the client needs to build the color scale + fit view.
+        assert "value_stats" in meta
+        assert "bounds" in meta and len(meta["bounds"]) == 4
+        assert meta["finest_res"] == 5
+        assert "layer_name" in meta
+
+    def test_immutable_cache_control(self, app_with_tiles, registered_ca):
+        client = TestClient(app_with_tiles)
+        r = client.get(f"/tiles/hex/{registered_ca}/metadata.json")
+        assert r.status_code == 200
+        cc = r.headers.get("cache-control", "")
+        assert "immutable" in cc and "public" in cc
+
+    def test_unknown_hash_returns_404(self, app_with_tiles):
+        client = TestClient(app_with_tiles)
+        r = client.get("/tiles/hex/deadbeefdeadbeef/metadata.json")
+        assert r.status_code == 404
+
+    def test_non_hex_namespace_returns_404(self, app_with_tiles, registered_ca):
+        client = TestClient(app_with_tiles)
+        r = client.get(f"/tiles/nothex/{registered_ca}/metadata.json")
+        assert r.status_code == 404
+
+    def test_metadata_url_derives_from_tile_url_suffix_swap(self, app_with_tiles, registered_ca):
+        """The contract the client relies on: swapping the tile_url's
+        `/{z}/{x}/{y}.pbf` suffix for `metadata.json` hits this route."""
+        client = TestClient(app_with_tiles)
+        tile_url = f"/tiles/hex/{registered_ca}/5/5/12.pbf"
+        meta_url = tile_url.rsplit("/", 3)[0] + "/metadata.json"
+        assert meta_url == f"/tiles/hex/{registered_ca}/metadata.json"
+        assert client.get(meta_url).status_code == 200

tiles/endpoint.py

@@ -15,7 +15,7 @@
 import time
 import anyio
 from starlette.requests import Request
-from starlette.responses import Response
+from starlette.responses import JSONResponse, Response
 
 from tiles.tile_math import (
     h3_edge_padding_deg,
@@ -267,6 +267,32 @@ def _run_tile_query(con, sql: str) -> bytes:
     return bytes(row[0])
 
 
+async def serve_metadata(request: Request) -> Response:
+    """GET /tiles/{namespace}/{name}/metadata.json
+
+    Serve the tileset's metadata sidecar (value_stats, bounds, layer_name,
+    value_columns, finest_res, ...) from the same origin as the tiles. The
+    client derives this URL from the tile_url template by swapping the
+    `/{z}/{x}/{y}.pbf` suffix for `metadata.json`, then reads the color-scale
+    inputs directly — so they never have to be transcribed through an LLM's
+    tool-call arguments (where weak models corrupt the large value_stats JSON,
+    silently dropping the layer-add; see the hex-not-showing investigation).
+    """
+    namespace = request.path_params["namespace"]
+    name = request.path_params["name"]
+
+    if namespace != "hex":
+        return Response(status_code=404)
+
+    con = request.app.state.tile_con
+    meta = await anyio.to_thread.run_sync(
+        _get_cached_metadata, request.app.state, con, namespace, name
+    )
+    if meta is None:
+        return Response(status_code=404)
+    return JSONResponse(meta, headers={"Cache-Control": TILE_CACHE_CONTROL})
+
+
 async def serve_tile(request: Request) -> Response:
     """GET /tiles/{namespace}/{name}/{z}/{x}/{y}.pbf"""
     namespace = request.path_params["namespace"]