feat: add real query cache coverage

coastwise/locations.py

@@ -0,0 +1,79 @@
+"""California coastal location parsing helpers."""
+
+from __future__ import annotations
+
+import re
+
+from coastwise.schemas import LocationContext
+
+
+LOCATION_ALIASES: dict[str, tuple[str, str, str]] = {
+    "crescent city": ("Crescent City", "northern", "Northern California ocean region"),
+    "fort bragg": ("Fort Bragg", "mendocino", "Mendocino California ocean region"),
+    "pacifica": ("Pacifica", "san_francisco", "San Francisco coast"),
+    "half moon bay": ("Half Moon Bay", "san_francisco", "San Francisco coast"),
+    "ocean beach": ("Ocean Beach SF", "san_francisco", "San Francisco coast"),
+    "monterey": ("Monterey", "central", "Central California ocean region"),
+    "santa barbara": ("Santa Barbara", "southern", "Southern California ocean region"),
+    "san diego bay": ("San Diego Bay", "southern", "Southern California ocean region"),
+    "san francisco bay": ("San Francisco Bay", "san_francisco_bay", "San Francisco Bay region"),
+}
+
+UNSUPPORTED_LOCATION_TERMS = ("lake", "tahoe", "river", "stream", "freshwater", "inland")
+
+
+def _normalize(value: str) -> str:
+    return " ".join(re.sub(r"[^a-z0-9]+", " ", value.casefold()).split())
+
+
+def parse_location(question: str, location_text: str | None = None) -> LocationContext:
+    """Parse a user-facing beach or coastal-area location."""
+
+    normalized_question = _normalize(question)
+    normalized_input = _normalize(location_text or "")
+    combined = " ".join(part for part in (normalized_input, normalized_question) if part)
+
+    if any(term in combined for term in UNSUPPORTED_LOCATION_TERMS):
+        return LocationContext(
+            raw_question_location=None,
+            raw_location_input=location_text or None,
+            matched_place=None,
+            area_or_scope="Unsupported non-coastal or non-ocean location",
+            confidence="unsupported",
+            warning="This MVP covers California ocean guidance, not freshwater, inland, or non-coastal locations.",
+            region_key=None,
+        )
+
+    for alias, (display, region_key, scope) in LOCATION_ALIASES.items():
+        if alias in combined:
+            raw_question_location = alias if alias in normalized_question else None
+            return LocationContext(
+                raw_question_location=raw_question_location,
+                raw_location_input=location_text or None,
+                matched_place=display,
+                area_or_scope=scope,
+                confidence="recognized",
+                warning=None,
+                region_key=region_key,
+            )
+
+    if normalized_input:
+        return LocationContext(
+            raw_question_location=None,
+            raw_location_input=location_text,
+            matched_place=None,
+            area_or_scope="General California ocean",
+            confidence="ambiguous",
+            warning="Location was not recognized clearly; local, area, or emergency rules may differ, so verify official local guidance before harvest.",
+            region_key=None,
+        )
+
+    return LocationContext(
+        raw_question_location=None,
+        raw_location_input=None,
+        matched_place=None,
+        area_or_scope="General California ocean",
+        confidence="absent",
+        warning="No location was provided; local, area, or emergency rules may differ, so verify official local guidance before harvest.",
+        region_key=None,
+    )

data/source-cache/seed/chunks.json

@@ -0,0 +1,110 @@
+[
+  {
+    "id": "chunk_lingcod_groundfish",
+    "source_id": "cdfw_groundfish_summary",
+    "source_url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+    "source_title": "CDFW Groundfish Summary",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Statewide Daily Bag Limits and Minimum Size Limits",
+    "text": "Lingcod, section 28.27, daily bag limit is 2 fish per person. Minimum size limit is 22 inches total length.",
+    "tokens": ["lingcod", "daily", "bag", "limit", "minimum", "size", "22", "inches"],
+    "species_or_category_terms": ["lingcod"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_dungeness_crab",
+    "source_id": "cdfw_crabs",
+    "source_url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+    "source_title": "CDFW Crabs",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Recreational Crab Fishery",
+    "text": "CDFW recreational crab fishery materials link Dungeness crab season, crab trap, hoop net, public health closure, and current recreational ocean fishing regulation information. Verify current CDFW crab rules and public health closures before harvest.",
+    "tokens": ["dungeness", "crab", "season", "trap", "hoop", "net", "public", "health", "closure", "verify"],
+    "species_or_category_terms": ["dungeness crab", "crab"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_cdph_quarantine",
+    "source_id": "cdph_annual_mussel_quarantine",
+    "source_url": "https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx",
+    "source_title": "CDPH Annual Mussel Quarantine",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Annual Mussel Quarantine",
+    "text": "The annual quarantine is normally in effect from May 1 through October 31 along the California coast. Cooking does not reliably destroy the toxins.",
+    "tokens": ["annual", "mussel", "quarantine", "may", "october", "california", "coast", "cooking", "toxins"],
+    "species_or_category_terms": ["mussel", "mussels", "shellfish"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_cdph_shellfish_verify",
+    "source_id": "cdph_shellfish_advisories",
+    "source_url": "https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+    "source_title": "CDPH Shellfish Advisories",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Shellfish Advisories",
+    "text": "CDPH shellfish advisories and recreational bivalve shellfish advisory map should be checked before harvesting or consuming sport-harvested shellfish.",
+    "tokens": ["cdph", "shellfish", "advisory", "map", "harvesting", "consuming", "verify"],
+    "species_or_category_terms": ["shellfish", "mussel", "mussels", "clams", "crab"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_monterey_regional",
+    "source_id": "cdfw_region_central",
+    "source_url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Central",
+    "source_title": "CDFW Central Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Central Region",
+    "text": "Central California ocean region source entry includes Monterey area context. Use cited regional snippets and verify current CDFW guidance when exact structured regional facts are unavailable.",
+    "tokens": ["central", "california", "ocean", "monterey", "regional", "verify"],
+    "species_or_category_terms": ["regional"],
+    "location_terms": ["monterey"]
+  },
+  {
+    "id": "chunk_dungeness_crab_season_context",
+    "source_id": "cdfw_crabs",
+    "source_url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+    "source_title": "CDFW Crabs",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Dungeness Crab Season Context",
+    "text": "Saved CDFW crab information references Dungeness crab season, crab trap rules, hoop net rules, public health closures, and current recreational ocean fishing regulation information for California ocean crab harvest. This saved cache does not include a clear open or closed season date for Fort Bragg or Pacifica.",
+    "tokens": ["saved", "cdfw", "dungeness", "crab", "season", "trap", "hoop", "net", "public", "health", "closure", "fort", "bragg", "pacifica"],
+    "species_or_category_terms": ["dungeness crab", "crab"],
+    "location_terms": ["fort bragg", "pacifica"]
+  },
+  {
+    "id": "chunk_rock_crab_context",
+    "source_id": "cdfw_crabs",
+    "source_url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+    "source_title": "CDFW Crabs",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Rock Crab Context",
+    "text": "Saved CDFW crab information covers recreational crab rules and public health closure context for crab species including rock crab. This saved cache does not confirm whether rock crab can be consumed.",
+    "tokens": ["saved", "cdfw", "crab", "rock", "public", "health", "closure", "consume"],
+    "species_or_category_terms": ["rock crab", "crab"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_cabezon_context",
+    "source_id": "cdfw_groundfish_summary",
+    "source_url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+    "source_title": "CDFW Groundfish Summary",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Cabezon Context",
+    "text": "Saved CDFW groundfish summary information includes cabezon as a groundfish species. Restrictions may include season, depth, bag, size, gear, and area rules, but this saved cache does not include a reviewed exact cabezon limit.",
+    "tokens": ["saved", "cdfw", "groundfish", "cabezon", "restrictions", "season", "depth", "bag", "size", "gear", "area"],
+    "species_or_category_terms": ["cabezon"],
+    "location_terms": []
+  },
+  {
+    "id": "chunk_half_moon_bay_shellfish_context",
+    "source_id": "cdph_shellfish_advisories",
+    "source_url": "https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+    "source_title": "CDPH Shellfish Advisories",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "heading": "Half Moon Bay Shellfish Context",
+    "text": "Saved CDPH shellfish advisory information should be checked for California coastal shellfish areas including Half Moon Bay. This saved cache does not certify shellfish safety for Half Moon Bay.",
+    "tokens": ["saved", "cdph", "shellfish", "advisory", "half", "moon", "bay", "safety"],
+    "species_or_category_terms": ["shellfish", "clams", "mussels"],
+    "location_terms": ["half moon bay"]
+  }
+]

tests/test_locations.py

@@ -0,0 +1,27 @@
+"""Location parsing tests."""
+
+from coastwise.locations import parse_location
+
+
+def test_parse_location_from_question_or_optional_beach_field():
+    pacifica = parse_location("can I eat mussels from Pacifica today?", "")
+    monterey = parse_location("what's the lingcod size?", "Monterey")
+    blank = parse_location("what's the min size of lingcod?", "")
+    unsupported = parse_location("what are trout rules?", "Lake Tahoe")
+
+    assert pacifica.matched_place == "Pacifica"
+    assert pacifica.region_key == "san_francisco"
+    assert monterey.matched_place == "Monterey"
+    assert monterey.region_key == "central"
+    assert blank.confidence == "absent"
+    assert "local" in (blank.warning or "").lower()
+    assert unsupported.confidence == "unsupported"
+    assert "california ocean" in (unsupported.warning or "").lower()
+
+
+def test_parse_location_recognizes_half_moon_bay_for_public_queries():
+    context = parse_location("is shellfish quarantine in half moon bay?", "")
+
+    assert context.matched_place == "Half Moon Bay"
+    assert context.region_key == "san_francisco"
+    assert context.confidence == "recognized"

tests/test_source_cache.py

@@ -0,0 +1,82 @@
+"""Source cache tests."""
+
+from dataclasses import replace
+from datetime import datetime, timedelta, timezone
+
+from coastwise.source_cache import (
+    DEFAULT_SEED_CACHE_DIR,
+    SourceCache,
+    cache_status_summary,
+    freshness_status,
+    load_seed_cache,
+    load_latest_cache,
+    validate_seed_cache,
+    write_runtime_cache,
+)
+from coastwise.schemas import FreshnessStatus, RefreshStatus, SourceSnapshot
+from coastwise.source_registry import load_official_sources, statewide_source_coverage
+
+
+def test_seed_cache_loads_and_covers_required_statewide_sources():
+    cache = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+    issues = validate_seed_cache(cache, load_official_sources(), statewide_source_coverage())
+
+    assert not [issue for issue in issues if issue.severity == "error"]
+    assert "lingcod_min_size" in cache.facts_by_id
+    assert "dungeness_crab_bag_limit" in cache.facts_by_id
+    assert not hasattr(cache, "question_history")
+    assert not hasattr(cache, "location_history")
+
+
+def test_freshness_status_uses_24_hour_threshold():
+    now = datetime(2026, 6, 14, 12, tzinfo=timezone.utc)
+
+    assert freshness_status(now - timedelta(hours=24), now) is FreshnessStatus.CURRENT
+    assert freshness_status(now - timedelta(hours=24, seconds=1), now) is FreshnessStatus.STALE
+
+
+def test_runtime_cache_overlays_valid_snapshot_and_preserves_seed_on_failure(tmp_path):
+    seed = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+    original = seed.snapshots_by_source_id["cdfw_ocean_regulations"]
+    replacement = SourceSnapshot(
+        source_id=original.source_id,
+        url=original.url,
+        title=original.title,
+        retrieved_at="2026-06-14T13:00:00+00:00",
+        content_hash="new-hash",
+        raw_text="Updated official source text",
+        origin="refresh",
+        refresh_status=RefreshStatus.UPDATED,
+    )
+
+    write_runtime_cache(tmp_path, seed, snapshots=(replacement,))
+    latest = load_latest_cache(seed, tmp_path)
+
+    assert latest.snapshots_by_source_id[original.source_id].content_hash == "new-hash"
+
+    preserved = load_latest_cache(seed, tmp_path)
+    assert preserved.snapshots_by_source_id["cdfw_groundfish_summary"].content_hash == seed.snapshots_by_source_id["cdfw_groundfish_summary"].content_hash
+
+
+def test_cache_status_summary_reports_seed_runtime_stale_and_no_cache():
+    now = datetime(2026, 6, 14, 13, tzinfo=timezone.utc)
+    seed = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+    stale = SourceCache(
+        sources=seed.sources,
+        snapshots=tuple(replace(snapshot, retrieved_at=now - timedelta(hours=25)) for snapshot in seed.snapshots),
+        chunks=seed.chunks,
+        facts=seed.facts,
+        advisory_facts=seed.advisory_facts,
+    )
+
+    assert cache_status_summary(seed, now)["usable_cache"] is True
+    assert cache_status_summary(stale, now)["freshness_status"] == "stale"
+    assert cache_status_summary(SourceCache((), (), (), ()), now)["freshness_status"] == "no_cache"
+
+
+def test_seed_cache_contains_real_query_saved_evidence_chunks():
+    cache = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+    text = " ".join(chunk.text.casefold() for chunk in cache.chunks)
+
+    for term in ("dungeness crab", "rock crab", "cabezon", "half moon bay", "pacifica"):
+        assert term in text