feat: add official source cache foundation

.gitignore

@@ -33,6 +33,7 @@ dist/
 # Local runtime data
 uploads/
 data/private/
+data/source-cache/runtime/
 *.sqlite
 *.sqlite3
 *.db

coastwise/__init__.py

@@ -1,2 +1,17 @@
 """CoastWise domain package."""
 
+__all__ = [
+    "advisories",
+    "ai",
+    "data",
+    "locations",
+    "qna",
+    "rules",
+    "schemas",
+    "search",
+    "source_cache",
+    "source_extract",
+    "source_refresh",
+    "source_registry",
+    "submission",
+]

coastwise/source_cache.py

@@ -0,0 +1,250 @@
+"""Seed and runtime cache helpers for official source snapshots."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timezone
+from enum import Enum
+from pathlib import Path
+
+from coastwise.schemas import (
+    AdvisoryFact,
+    FreshnessStatus,
+    OfficialSource,
+    RefreshStatus,
+    SourceChunk,
+    SourceSnapshot,
+    StatewideSourceCoverage,
+    StructuredRegulationFact,
+    ValidationIssue,
+)
+from coastwise.source_registry import load_official_sources
+
+DEFAULT_SOURCE_CACHE_ROOT = Path(__file__).resolve().parent.parent / "data" / "source-cache"
+DEFAULT_SEED_CACHE_DIR = DEFAULT_SOURCE_CACHE_ROOT / "seed"
+DEFAULT_RUNTIME_CACHE_DIR = DEFAULT_SOURCE_CACHE_ROOT / "runtime"
+
+
+@dataclass(frozen=True)
+class SourceCache:
+    sources: tuple[OfficialSource, ...]
+    snapshots: tuple[SourceSnapshot, ...]
+    chunks: tuple[SourceChunk, ...]
+    facts: tuple[StructuredRegulationFact, ...]
+    advisory_facts: tuple[AdvisoryFact, ...] = ()
+
+    @property
+    def sources_by_id(self) -> dict[str, OfficialSource]:
+        return {source.id: source for source in self.sources}
+
+    @property
+    def snapshots_by_source_id(self) -> dict[str, SourceSnapshot]:
+        return {snapshot.source_id: snapshot for snapshot in self.snapshots}
+
+    @property
+    def chunks_by_id(self) -> dict[str, SourceChunk]:
+        return {chunk.id: chunk for chunk in self.chunks}
+
+    @property
+    def facts_by_id(self) -> dict[str, StructuredRegulationFact]:
+        return {fact.id: fact for fact in self.facts}
+
+    @property
+    def advisory_facts_by_id(self) -> dict[str, AdvisoryFact]:
+        return {fact.id: fact for fact in self.advisory_facts}
+
+
+def _load_json(path: Path, fallback):
+    if not path.exists():
+        return fallback
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _json_ready(value):
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, tuple):
+        return [_json_ready(item) for item in value]
+    if isinstance(value, list):
+        return [_json_ready(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _json_ready(item) for key, item in value.items()}
+    return value
+
+
+def _source_from_dict(value: dict) -> OfficialSource:
+    return OfficialSource(**value)
+
+
+def _snapshot_from_dict(value: dict) -> SourceSnapshot:
+    return SourceSnapshot(**value)
+
+
+def _chunk_from_dict(value: dict) -> SourceChunk:
+    return SourceChunk(**value)
+
+
+def _fact_from_dict(value: dict) -> StructuredRegulationFact:
+    return StructuredRegulationFact(**value)
+
+
+def _advisory_from_dict(value: dict) -> AdvisoryFact:
+    return AdvisoryFact(**value)
+
+
+def load_seed_cache(seed_dir: Path = DEFAULT_SEED_CACHE_DIR) -> SourceCache:
+    """Load reviewed bundled seed source snapshots, chunks, and facts."""
+
+    sources_data = _load_json(seed_dir / "sources.json", [])
+    snapshots_data = _load_json(seed_dir / "snapshots.json", [])
+    chunks_data = _load_json(seed_dir / "chunks.json", [])
+    facts_data = _load_json(seed_dir / "facts.json", {})
+
+    if isinstance(facts_data, list):
+        structured_data = facts_data
+        advisory_data = []
+    else:
+        structured_data = facts_data.get("structured_facts", [])
+        advisory_data = facts_data.get("advisory_facts", [])
+
+    sources = tuple(_source_from_dict(item) for item in sources_data) or tuple(load_official_sources())
+    return SourceCache(
+        sources=sources,
+        snapshots=tuple(_snapshot_from_dict(item) for item in snapshots_data),
+        chunks=tuple(_chunk_from_dict(item) for item in chunks_data),
+        facts=tuple(_fact_from_dict(item) for item in structured_data),
+        advisory_facts=tuple(_advisory_from_dict(item) for item in advisory_data),
+    )
+
+
+def load_latest_cache(
+    seed_cache: SourceCache,
+    runtime_cache_path: Path = DEFAULT_RUNTIME_CACHE_DIR,
+) -> SourceCache:
+    """Overlay valid runtime cache files on top of the reviewed seed cache."""
+
+    if not runtime_cache_path.exists():
+        return seed_cache
+    runtime = load_seed_cache(runtime_cache_path)
+    snapshots_by_source = seed_cache.snapshots_by_source_id
+    snapshots_by_source.update(runtime.snapshots_by_source_id)
+    facts = {fact.id: fact for fact in seed_cache.facts}
+    facts.update({fact.id: fact for fact in runtime.facts})
+    advisory_facts = {fact.id: fact for fact in seed_cache.advisory_facts}
+    advisory_facts.update({fact.id: fact for fact in runtime.advisory_facts})
+    chunks = {chunk.id: chunk for chunk in seed_cache.chunks}
+    chunks.update({chunk.id: chunk for chunk in runtime.chunks})
+    return SourceCache(
+        sources=seed_cache.sources,
+        snapshots=tuple(snapshots_by_source.values()),
+        chunks=tuple(chunks.values()),
+        facts=tuple(facts.values()),
+        advisory_facts=tuple(advisory_facts.values()),
+    )
+
+
+def write_runtime_cache(
+    runtime_cache_path: Path,
+    base_cache: SourceCache,
+    *,
+    snapshots: tuple[SourceSnapshot, ...] = (),
+    chunks: tuple[SourceChunk, ...] = (),
+    facts: tuple[StructuredRegulationFact, ...] = (),
+    advisory_facts: tuple[AdvisoryFact, ...] = (),
+) -> None:
+    """Persist valid refreshed public source data without user history."""
+
+    runtime_cache_path.mkdir(parents=True, exist_ok=True)
+    payloads = {
+        "sources.json": [asdict(source) for source in base_cache.sources],
+        "snapshots.json": [asdict(snapshot) for snapshot in snapshots],
+        "chunks.json": [asdict(chunk) for chunk in chunks],
+        "facts.json": {
+            "structured_facts": [asdict(fact) for fact in facts],
+            "advisory_facts": [asdict(fact) for fact in advisory_facts],
+        },
+    }
+    for filename, payload in payloads.items():
+        with (runtime_cache_path / filename).open("w", encoding="utf-8") as handle:
+            json.dump(_json_ready(payload), handle, indent=2, sort_keys=True)
+
+
+def freshness_status(retrieved_at: datetime | str | None, now: datetime) -> FreshnessStatus:
+    if retrieved_at is None:
+        return FreshnessStatus.NO_CACHE
+    retrieved = (
+        retrieved_at
+        if isinstance(retrieved_at, datetime)
+        else datetime.fromisoformat(retrieved_at.replace("Z", "+00:00"))
+    )
+    if retrieved.tzinfo is None:
+        retrieved = retrieved.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    return FreshnessStatus.STALE if (now - retrieved).total_seconds() > 24 * 60 * 60 else FreshnessStatus.CURRENT
+
+
+def validate_seed_cache(
+    cache: SourceCache,
+    sources: list[OfficialSource],
+    coverage: StatewideSourceCoverage,
+) -> list[ValidationIssue]:
+    """Validate seed cache coverage for MVP-required official sources."""
+
+    issues: list[ValidationIssue] = []
+    source_ids = {source.id for source in sources}
+    snapshot_ids = set(cache.snapshots_by_source_id)
+
+    for source_id in coverage.required_source_ids:
+        if source_id not in source_ids:
+            issues.append(ValidationIssue(source_id, "error", "Required source is missing from registry."))
+        if source_id not in snapshot_ids:
+            issues.append(ValidationIssue(source_id, "error", "Required source is missing seed snapshot."))
+
+    for fact_id in ("lingcod_min_size", "dungeness_crab_bag_limit"):
+        if fact_id not in cache.facts_by_id:
+            issues.append(ValidationIssue(fact_id, "error", "Required validation-set fact is missing."))
+    for advisory_id in ("cdph_annual_mussel_quarantine", "cdph_shellfish_verify"):
+        if advisory_id not in cache.advisory_facts_by_id:
+            issues.append(ValidationIssue(advisory_id, "error", "Required CDPH advisory fact is missing."))
+
+    return issues
+
+
+def refresh_status_for_cache(cache: SourceCache) -> RefreshStatus:
+    """Return a conservative aggregate refresh status for loaded cache."""
+
+    if not cache.snapshots:
+        return RefreshStatus.UNAVAILABLE
+    if any(snapshot.refresh_status is RefreshStatus.FAILED for snapshot in cache.snapshots):
+        return RefreshStatus.FAILED
+    return RefreshStatus.UNCHANGED
+
+
+def cache_status_summary(cache: SourceCache, now: datetime) -> dict[str, object]:
+    """Summarize current/stale/no-cache state for UI rendering."""
+
+    if not cache.snapshots:
+        return {
+            "usable_cache": False,
+            "freshness_status": FreshnessStatus.NO_CACHE.value,
+            "latest_retrieved_at": None,
+            "message": "No usable official source cache is available.",
+        }
+    newest = max(snapshot.retrieved_at for snapshot in cache.snapshots)
+    stale = any(freshness_status(snapshot.retrieved_at, now) is FreshnessStatus.STALE for snapshot in cache.snapshots)
+    status = FreshnessStatus.STALE if stale else FreshnessStatus.CURRENT
+    return {
+        "usable_cache": True,
+        "freshness_status": status.value,
+        "latest_retrieved_at": newest.isoformat(),
+        "message": (
+            "Answering from stale cached official source data; verify official sources before harvest."
+            if stale
+            else "Answering from current cached official source data."
+        ),
+    }

coastwise/source_extract.py

@@ -0,0 +1,219 @@
+"""Official source text extraction helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+from dataclasses import dataclass
+
+from coastwise.schemas import (
+    RequestedFactType,
+    SourceChunk,
+    SourceSnapshot,
+    StructuredRegulationFact,
+    StructuredValidationSet,
+    ValidationIssue,
+)
+
+
+def normalize_source_text(value: str) -> str:
+    """Return compact source text suitable for deterministic cache hashing."""
+
+    without_tags = re.sub(r"<[^>]+>", " ", value)
+    decoded = html.unescape(without_tags)
+    return " ".join(decoded.split())
+
+
+def content_hash(value: str) -> str:
+    """Return a stable content hash for normalized source text."""
+
+    return hashlib.sha256(normalize_source_text(value).encode("utf-8")).hexdigest()
+
+
+def tokenize_source_text(value: str) -> tuple[str, ...]:
+    """Tokenize source text for simple retrieval."""
+
+    tokens = re.findall(r"[a-z0-9]+", value.casefold())
+    return tuple(dict.fromkeys(tokens))
+
+
+def _species_terms(text: str) -> tuple[str, ...]:
+    known = (
+        "lingcod",
+        "dungeness crab",
+        "mussel",
+        "mussels",
+        "shellfish",
+        "rockfish",
+        "monterey",
+        "pacifica",
+    )
+    lowered = text.casefold()
+    return tuple(term for term in known if term in lowered)
+
+
+def _location_terms(text: str) -> tuple[str, ...]:
+    known = ("pacifica", "ocean beach", "monterey", "crescent city", "santa barbara", "san diego bay")
+    lowered = text.casefold()
+    return tuple(term for term in known if term in lowered)
+
+
+def extract_source_chunks(snapshot: SourceSnapshot, *, max_chars: int = 900) -> list[SourceChunk]:
+    """Split a source snapshot into traceable chunks."""
+
+    text = normalize_source_text(snapshot.raw_text)
+    if not text:
+        return []
+
+    parts = re.split(r"(?<=[.!?])\s+", text)
+    chunks: list[SourceChunk] = []
+    current = ""
+    index = 1
+    for part in parts:
+        candidate = f"{current} {part}".strip()
+        if len(candidate) > max_chars and current:
+            chunks.append(
+                SourceChunk(
+                    id=f"{snapshot.source_id}:chunk:{index}",
+                    source_id=snapshot.source_id,
+                    source_url=snapshot.url,
+                    source_title=snapshot.title,
+                    retrieved_at=snapshot.retrieved_at,
+                    heading=None,
+                    text=current,
+                    tokens=tokenize_source_text(current),
+                    species_or_category_terms=_species_terms(current),
+                    location_terms=_location_terms(current),
+                )
+            )
+            index += 1
+            current = part
+        else:
+            current = candidate
+
+    if current:
+        chunks.append(
+            SourceChunk(
+                id=f"{snapshot.source_id}:chunk:{index}",
+                source_id=snapshot.source_id,
+                source_url=snapshot.url,
+                source_title=snapshot.title,
+                retrieved_at=snapshot.retrieved_at,
+                heading=None,
+                text=current,
+                tokens=tokenize_source_text(current),
+                species_or_category_terms=_species_terms(current),
+                location_terms=_location_terms(current),
+            )
+        )
+    return chunks
+
+
+@dataclass(frozen=True)
+class ExtractionResult:
+    facts: tuple[StructuredRegulationFact, ...]
+    issues: tuple[ValidationIssue, ...] = ()
+
+
+def default_structured_validation_set() -> StructuredValidationSet:
+    return StructuredValidationSet(
+        id="mvp_validation",
+        required_questions=(
+            "what's the min size of lingcod?",
+            "any size limit for lingcod?",
+            "bag limit for Dungeness crab?",
+        ),
+        required_species_or_categories=("lingcod", "dungeness_crab", "mussels", "shellfish"),
+        required_fact_types=(
+            RequestedFactType.MINIMUM_SIZE,
+            RequestedFactType.BAG_LIMIT,
+            RequestedFactType.QUARANTINE,
+            RequestedFactType.ADVISORY,
+        ),
+        required_sources=(
+            "cdfw_groundfish_summary",
+            "cdfw_crabs",
+            "cdph_annual_mussel_quarantine",
+            "cdph_shellfish_advisories",
+        ),
+        required_statewide_coverage_id="statewide_ca_ocean",
+    )
+
+
+def extract_structured_facts(
+    chunks: tuple[SourceChunk, ...] | list[SourceChunk],
+    validation_set: StructuredValidationSet,
+) -> ExtractionResult:
+    """Extract the small reviewed validation-set facts from source chunks."""
+
+    facts: list[StructuredRegulationFact] = []
+    issues: list[ValidationIssue] = []
+    for chunk in chunks:
+        lowered = chunk.text.casefold()
+        if "lingcod" in lowered and "22" in lowered:
+            facts.append(
+                StructuredRegulationFact(
+                    id="lingcod_min_size",
+                    species_or_category="lingcod",
+                    display_name="Lingcod",
+                    aliases=("ling cod",),
+                    area_or_scope="California ocean statewide groundfish regulations",
+                    fact_type=RequestedFactType.MINIMUM_SIZE,
+                    value="22",
+                    units="inches total length",
+                    source_id=chunk.source_id,
+                    source_url=chunk.source_url,
+                    retrieved_at=chunk.retrieved_at,
+                    supporting_chunk_id=chunk.id,
+                    supporting_snippet=chunk.text,
+                    validation_set=True,
+                )
+            )
+        if "lingcod" in lowered and "2 fish" in lowered:
+            facts.append(
+                StructuredRegulationFact(
+                    id="lingcod_bag_limit",
+                    species_or_category="lingcod",
+                    display_name="Lingcod",
+                    aliases=("ling cod",),
+                    area_or_scope="California ocean statewide groundfish regulations",
+                    fact_type=RequestedFactType.BAG_LIMIT,
+                    value="2",
+                    units="fish per person",
+                    source_id=chunk.source_id,
+                    source_url=chunk.source_url,
+                    retrieved_at=chunk.retrieved_at,
+                    supporting_chunk_id=chunk.id,
+                    supporting_snippet=chunk.text,
+                    validation_set=True,
+                )
+            )
+        if "dungeness crab" in lowered:
+            facts.append(
+                StructuredRegulationFact(
+                    id="dungeness_crab_bag_limit",
+                    species_or_category="dungeness_crab",
+                    display_name="Dungeness crab",
+                    aliases=("dungeness crabs", "crab"),
+                    area_or_scope="California recreational crab fishery",
+                    fact_type=RequestedFactType.GENERAL_SUMMARY,
+                    value=(
+                        "Verify current CDFW Dungeness crab season, trap/hoop-net rules, "
+                        "public health closures, and crab rules before harvest."
+                    ),
+                    units=None,
+                    source_id=chunk.source_id,
+                    source_url=chunk.source_url,
+                    retrieved_at=chunk.retrieved_at,
+                    supporting_chunk_id=chunk.id,
+                    supporting_snippet=chunk.text,
+                    validation_set=True,
+                )
+            )
+
+    fact_ids = {fact.id for fact in facts}
+    for required_id in ("lingcod_min_size", "lingcod_bag_limit", "dungeness_crab_bag_limit"):
+        if required_id not in fact_ids:
+            issues.append(ValidationIssue(required_id, "error", "Required structured fact was not extracted."))
+    return ExtractionResult(facts=tuple(facts), issues=tuple(issues))

coastwise/source_refresh.py

@@ -0,0 +1,99 @@
+"""Official source refresh helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from urllib.request import Request, urlopen
+
+from coastwise.schemas import OfficialSource, RefreshResult, RefreshStatus, SourceSnapshot
+from coastwise.source_cache import SourceCache
+from coastwise.source_extract import content_hash, extract_source_chunks, normalize_source_text
+
+Fetcher = Callable[[OfficialSource], str]
+
+
+def fetch_official_source(source: OfficialSource, *, timeout: float = 8.0) -> str:
+    """Fetch an official source with standard-library networking."""
+
+    request = Request(source.url, headers={"User-Agent": "CoastWise/0.1"})
+    with urlopen(request, timeout=timeout) as response:
+        return response.read().decode("utf-8", errors="replace")
+
+
+def refresh_official_sources(
+    sources: list[OfficialSource],
+    cache: SourceCache,
+    now: datetime,
+    fetcher: Fetcher | None = None,
+) -> tuple[RefreshResult, SourceCache]:
+    """Refresh official sources without replacing last-good failed snapshots."""
+
+    fetch = fetcher or fetch_official_source
+    source_results: dict[str, RefreshStatus] = {}
+    updated_ids: list[str] = []
+    unchanged_ids: list[str] = []
+    failed_ids: list[str] = []
+    preserved_ids: list[str] = []
+    snapshots_by_source = cache.snapshots_by_source_id
+    chunks_by_id = cache.chunks_by_id
+
+    for source in sources:
+        try:
+            raw = fetch(source)
+            normalized = normalize_source_text(raw)
+            if not normalized:
+                raise ValueError("empty source content")
+            previous = snapshots_by_source.get(source.id)
+            if previous is not None and normalize_source_text(previous.raw_text) == normalized:
+                source_results[source.id] = RefreshStatus.UNCHANGED
+                unchanged_ids.append(source.id)
+                continue
+
+            snapshot = SourceSnapshot(
+                source_id=source.id,
+                url=source.url,
+                title=source.title,
+                retrieved_at=now,
+                content_hash=content_hash(normalized),
+                raw_text=normalized,
+                origin="refresh",
+                refresh_status=RefreshStatus.UPDATED,
+            )
+            snapshots_by_source[source.id] = snapshot
+            for chunk in extract_source_chunks(snapshot):
+                chunks_by_id[chunk.id] = chunk
+            source_results[source.id] = RefreshStatus.UPDATED
+            updated_ids.append(source.id)
+        except Exception:
+            source_results[source.id] = RefreshStatus.FAILED
+            failed_ids.append(source.id)
+            if source.id in snapshots_by_source:
+                preserved_ids.append(source.id)
+
+    message_parts = [
+        f"CDFW/CDPH sources checked: {len(updated_ids)} updated",
+        f"{len(unchanged_ids)} unchanged",
+        f"{len(failed_ids)} failed",
+    ]
+    if preserved_ids:
+        message_parts.append("last-good cache is still being used for failed sources")
+
+    result = RefreshResult(
+        started_at=now,
+        completed_at=now,
+        source_results=source_results,
+        updated_source_ids=tuple(updated_ids),
+        unchanged_source_ids=tuple(unchanged_ids),
+        failed_source_ids=tuple(failed_ids),
+        cache_preserved_source_ids=tuple(preserved_ids),
+        user_message=", ".join(message_parts) + ".",
+    )
+    refreshed_cache = SourceCache(
+        sources=cache.sources,
+        snapshots=tuple(snapshots_by_source.values()),
+        chunks=tuple(chunks_by_id.values()),
+        facts=cache.facts,
+        advisory_facts=cache.advisory_facts,
+    )
+    return result, refreshed_cache

coastwise/source_registry.py

@@ -0,0 +1,185 @@
+"""Official source registry for source-backed CoastWise answers."""
+
+from __future__ import annotations
+
+from coastwise.schemas import OfficialSource, OfficialSourceType, StatewideSourceCoverage, ValidationIssue
+
+APPROVED_HOSTS = ("wildlife.ca.gov", "cdph.ca.gov", "www.cdph.ca.gov")
+
+REGION_KEYS = (
+    "northern",
+    "mendocino",
+    "san_francisco",
+    "central",
+    "southern",
+    "san_francisco_bay",
+)
+
+
+def load_official_sources() -> list[OfficialSource]:
+    """Return the curated CDFW/CDPH official source allowlist."""
+
+    return [
+        OfficialSource(
+            id="cdfw_ocean_regulations",
+            title="CDFW Ocean Sport Fishing Regulations",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGULATIONS,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations",
+            scope="Statewide California ocean sport fishing regulations",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_inseason_changes",
+            title="CDFW Ocean Sport Fishing In-Season Regulation Changes",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGULATIONS,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Inseason",
+            scope="Statewide California ocean in-season regulation changes",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_northern",
+            title="CDFW Northern Ocean Region",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGION_MAP,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Northern",
+            scope="Northern California ocean region",
+            region_key="northern",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_mendocino",
+            title="CDFW Mendocino Ocean Region",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGION_MAP,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Mendocino",
+            scope="Mendocino California ocean region",
+            region_key="mendocino",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_san_francisco",
+            title="CDFW San Francisco Ocean Region",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGION_MAP,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/San-Francisco",
+            scope="San Francisco California ocean region",
+            region_key="san_francisco",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_central",
+            title="CDFW Central Ocean Region",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGION_MAP,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Central",
+            scope="Central California ocean region",
+            region_key="central",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_southern",
+            title="CDFW Southern Ocean Region",
+            source_type=OfficialSourceType.CDFW_OCEAN_REGION_MAP,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Southern",
+            scope="Southern California ocean region",
+            region_key="southern",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_region_san_francisco_bay",
+            title="CDFW San Francisco Bay Region",
+            source_type=OfficialSourceType.CDFW_REGIONAL_REGULATIONS,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/SF-Bay",
+            scope="San Francisco Bay sport fishing region",
+            region_key="san_francisco_bay",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_groundfish_summary",
+            title="CDFW Groundfish Summary",
+            source_type=OfficialSourceType.CDFW_SPECIES_REGULATIONS,
+            url="https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+            scope="California ocean groundfish summaries",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdfw_crabs",
+            title="CDFW Crabs",
+            source_type=OfficialSourceType.CDFW_SPECIES_REGULATIONS,
+            url="https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+            scope="California ocean crab regulations",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdph_shellfish_advisories",
+            title="CDPH Shellfish Advisories",
+            source_type=OfficialSourceType.CDPH_SHELLFISH_ADVISORY,
+            url="https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+            scope="California shellfish advisories",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+        OfficialSource(
+            id="cdph_annual_mussel_quarantine",
+            title="CDPH Annual Mussel Quarantine",
+            source_type=OfficialSourceType.CDPH_ANNUAL_MUSSEL_QUARANTINE,
+            url="https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx",
+            scope="California annual mussel quarantine",
+            statewide_required=True,
+            required_for_mvp=True,
+        ),
+    ]
+
+
+def statewide_source_coverage() -> StatewideSourceCoverage:
+    """Return the statewide California ocean source coverage guarantee."""
+
+    return StatewideSourceCoverage(
+        id="statewide_ca_ocean",
+        required_region_keys=REGION_KEYS,
+        required_source_ids=tuple(source.id for source in load_official_sources() if source.required_for_mvp),
+        general_source_ids=(
+            "cdfw_ocean_regulations",
+            "cdfw_inseason_changes",
+            "cdfw_groundfish_summary",
+            "cdfw_crabs",
+        ),
+        cdph_source_ids=("cdph_shellfish_advisories", "cdph_annual_mussel_quarantine"),
+    )
+
+
+def source_by_id(source_id: str) -> OfficialSource | None:
+    return {source.id: source for source in load_official_sources()}.get(source_id)
+
+
+def validate_source_registry(sources: list[OfficialSource]) -> list[ValidationIssue]:
+    """Validate official-only source coverage and URL policy."""
+
+    issues: list[ValidationIssue] = []
+    seen: set[str] = set()
+    for source in sources:
+        if source.id in seen:
+            issues.append(ValidationIssue("id", "error", f"Duplicate source id: {source.id}"))
+        seen.add(source.id)
+        if not source.url.startswith("https://"):
+            issues.append(ValidationIssue(source.id, "error", "Source URLs must use HTTPS."))
+        if not any(host in source.url for host in APPROVED_HOSTS):
+            issues.append(ValidationIssue(source.id, "error", "Source URL is not CDFW/CDPH official."))
+
+    by_region = {source.region_key for source in sources if source.region_key}
+    for region_key in REGION_KEYS:
+        if region_key not in by_region:
+            issues.append(ValidationIssue(region_key, "error", "Missing statewide region source."))
+
+    coverage = statewide_source_coverage()
+    source_ids = {source.id for source in sources}
+    for source_id in coverage.required_source_ids:
+        if source_id not in source_ids:
+            issues.append(ValidationIssue(source_id, "error", "Missing MVP-required source."))
+    return issues

data/source-cache/seed-manifest.json

@@ -0,0 +1,7 @@
+{
+  "id": "coastwise-source-cache-seed-2026-06-14",
+  "reviewed_at": "2026-06-14T12:00:00+00:00",
+  "coverage_id": "statewide_ca_ocean",
+  "stale_after_hours": 24,
+  "notes": "Reviewed seed cache for source-backed MVP validation. Online refresh replaces last-good snapshots when available."
+}

data/source-cache/seed/.gitkeep

@@ -0,0 +1 @@
+

data/source-cache/seed/facts.json

@@ -0,0 +1,79 @@
+{
+  "structured_facts": [
+    {
+      "id": "lingcod_min_size",
+      "species_or_category": "lingcod",
+      "display_name": "Lingcod",
+      "aliases": ["ling cod"],
+      "area_or_scope": "California ocean statewide groundfish regulations",
+      "fact_type": "minimum_size",
+      "value": "22",
+      "units": "inches total length",
+      "source_id": "cdfw_groundfish_summary",
+      "source_url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+      "retrieved_at": "2026-06-14T12:00:00+00:00",
+      "supporting_chunk_id": "chunk_lingcod_groundfish",
+      "supporting_snippet": "Lingcod, section 28.27, daily bag limit is 2 fish per person. Minimum size limit is 22 inches total length.",
+      "validation_set": true
+    },
+    {
+      "id": "lingcod_bag_limit",
+      "species_or_category": "lingcod",
+      "display_name": "Lingcod",
+      "aliases": ["ling cod"],
+      "area_or_scope": "California ocean statewide groundfish regulations",
+      "fact_type": "bag_limit",
+      "value": "2",
+      "units": "fish per person",
+      "source_id": "cdfw_groundfish_summary",
+      "source_url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+      "retrieved_at": "2026-06-14T12:00:00+00:00",
+      "supporting_chunk_id": "chunk_lingcod_groundfish",
+      "supporting_snippet": "Lingcod, section 28.27, daily bag limit is 2 fish per person. Minimum size limit is 22 inches total length.",
+      "validation_set": true
+    },
+    {
+      "id": "dungeness_crab_bag_limit",
+      "species_or_category": "dungeness_crab",
+      "display_name": "Dungeness crab",
+      "aliases": ["dungeness crabs", "crab"],
+      "area_or_scope": "California recreational crab fishery",
+      "fact_type": "general_summary",
+      "value": "Verify current CDFW Dungeness crab season, trap/hoop-net rules, public health closures, and crab rules before harvest.",
+      "source_id": "cdfw_crabs",
+      "source_url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+      "retrieved_at": "2026-06-14T12:00:00+00:00",
+      "supporting_chunk_id": "chunk_dungeness_crab",
+      "supporting_snippet": "CDFW recreational crab fishery materials link Dungeness crab season, crab trap, hoop net, public health closure, and current recreational ocean fishing regulation information.",
+      "validation_set": true
+    }
+  ],
+  "advisory_facts": [
+    {
+      "id": "cdph_annual_mussel_quarantine",
+      "affected_species_or_category": "mussels",
+      "area_or_scope": "California coast statewide",
+      "advisory_status": "Annual mussel quarantine normally applies May 1 through October 31.",
+      "effective_start": "2026-05-01",
+      "effective_end": "2026-10-31",
+      "warning": "Do not harvest sport-harvested mussels during the annual quarantine. Cooking does not reliably destroy the toxins.",
+      "source_id": "cdph_annual_mussel_quarantine",
+      "source_url": "https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx",
+      "retrieved_at": "2026-06-14T12:00:00+00:00",
+      "supporting_chunk_id": "chunk_cdph_quarantine",
+      "supporting_snippet": "The annual quarantine is normally in effect from May 1 through October 31 along the California coast. Cooking does not reliably destroy the toxins."
+    },
+    {
+      "id": "cdph_shellfish_verify",
+      "affected_species_or_category": "shellfish",
+      "area_or_scope": "California coast statewide",
+      "advisory_status": "Verify current CDPH shellfish advisories before harvest or consumption.",
+      "warning": "CDPH verification remains necessary even when cached advisory data is current.",
+      "source_id": "cdph_shellfish_advisories",
+      "source_url": "https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+      "retrieved_at": "2026-06-14T12:00:00+00:00",
+      "supporting_chunk_id": "chunk_cdph_shellfish_verify",
+      "supporting_snippet": "CDPH shellfish advisories and recreational bivalve shellfish advisory map should be checked before harvesting or consuming sport-harvested shellfish."
+    }
+  ]
+}

data/source-cache/seed/snapshots.json

@@ -0,0 +1,122 @@
+[
+  {
+    "source_id": "cdfw_ocean_regulations",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations",
+    "title": "CDFW Ocean Sport Fishing Regulations",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-cdfw-ocean-regulations",
+    "raw_text": "CDFW Ocean Sport Fishing Regulations provide statewide ocean regulation links, current sport fishing regulation PDFs, in-season ocean fishing regulation changes, the interactive ocean sport fishing map, and current sport fishing regulations by species or category. Where no bag limit is listed, fish are 20 finfish in combination with not more than 10 of any one species; shellfish are 35 of any one species.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_inseason_changes",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Inseason",
+    "title": "CDFW Ocean Sport Fishing In-Season Regulation Changes",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-cdfw-inseason",
+    "raw_text": "CDFW in-season ocean fishing regulation changes summarize current emergency and in-season changes. Users must check current CDFW guidance before fishing or harvesting.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_northern",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Northern",
+    "title": "CDFW Northern Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-northern",
+    "raw_text": "Northern California ocean region source entry for statewide CoastWise coverage. Use official CDFW source evidence and snippet fallback when structured regional facts are unavailable.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_mendocino",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Mendocino",
+    "title": "CDFW Mendocino Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-mendocino",
+    "raw_text": "Mendocino California ocean region source entry for statewide CoastWise coverage. Use official CDFW source evidence and snippet fallback when structured regional facts are unavailable.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_san_francisco",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/San-Francisco",
+    "title": "CDFW San Francisco Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-san-francisco",
+    "raw_text": "San Francisco California ocean region source entry for statewide CoastWise coverage. Point Arena to Pigeon Point rules can differ from San Francisco Bay rules.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_central",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Central",
+    "title": "CDFW Central Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-central",
+    "raw_text": "Central California ocean region source entry for statewide CoastWise coverage, including Monterey and Santa Cruz area context. Use cited regional snippets when exact structured facts are unavailable.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_southern",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Southern",
+    "title": "CDFW Southern Ocean Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-southern",
+    "raw_text": "Southern California ocean region source entry for statewide CoastWise coverage, including Santa Barbara and San Diego area context. Use cited regional snippets when exact structured facts are unavailable.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_region_san_francisco_bay",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/SF-Bay",
+    "title": "CDFW San Francisco Bay Region",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-region-sf-bay",
+    "raw_text": "San Francisco Bay region source entry for statewide CoastWise coverage. Bay rules can differ from adjacent ocean coast rules; users must verify Bay-specific CDFW guidance.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_groundfish_summary",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+    "title": "CDFW Groundfish Summary",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-groundfish-summary",
+    "raw_text": "CDFW Summary of Recreational Groundfish Fishing Regulations updated January 6, 2026. These regulations are subject to in-season change. Lingcod, section 28.27, daily bag limit is 2 fish per person. Minimum size limit is 22 inches total length. Filleting aboard a vessel requires minimum 14 inches in length with the entire skin attached.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdfw_crabs",
+    "url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+    "title": "CDFW Crabs",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-crabs",
+    "raw_text": "CDFW Invertebrates of Interest: Crabs includes recreational Dungeness and rock crab regulations, public health hazard closures, trap and hoop net regulation summaries, and recreational crab fishery links. Recreational crab questions must verify current CDFW crab pages, public health closures, and gear restrictions.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdph_shellfish_advisories",
+    "url": "https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+    "title": "CDPH Shellfish Advisories",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-cdph-shellfish",
+    "raw_text": "CDPH shellfish advisories and the recreational bivalve shellfish advisory map provide current health advisories for shellfish, crab, and related marine biotoxin risks. Users must verify CDPH before harvesting or consuming sport-harvested shellfish.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  },
+  {
+    "source_id": "cdph_annual_mussel_quarantine",
+    "url": "https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx",
+    "title": "CDPH Annual Mussel Quarantine",
+    "retrieved_at": "2026-06-14T12:00:00+00:00",
+    "content_hash": "seed-cdph-quarantine",
+    "raw_text": "CDPH annual mussel quarantine applies only to sport-harvested mussels. The annual quarantine is normally in effect from May 1 through October 31. It is in effect along the California coast from the Oregon border to the Mexican border, including all bays, inlets and harbors. Cooking does not reliably destroy the toxins.",
+    "origin": "seed",
+    "refresh_status": "unchanged"
+  }
+]

data/source-cache/seed/sources.json

@@ -0,0 +1,116 @@
+[
+  {
+    "id": "cdfw_ocean_regulations",
+    "title": "CDFW Ocean Sport Fishing Regulations",
+    "source_type": "cdfw_ocean_regulations",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations",
+    "scope": "Statewide California ocean sport fishing regulations",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_inseason_changes",
+    "title": "CDFW Ocean Sport Fishing In-Season Regulation Changes",
+    "source_type": "cdfw_ocean_regulations",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Inseason",
+    "scope": "Statewide California ocean in-season regulation changes",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_northern",
+    "title": "CDFW Northern Ocean Region",
+    "source_type": "cdfw_ocean_region_map",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Northern",
+    "scope": "Northern California ocean region",
+    "region_key": "northern",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_mendocino",
+    "title": "CDFW Mendocino Ocean Region",
+    "source_type": "cdfw_ocean_region_map",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Mendocino",
+    "scope": "Mendocino California ocean region",
+    "region_key": "mendocino",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_san_francisco",
+    "title": "CDFW San Francisco Ocean Region",
+    "source_type": "cdfw_ocean_region_map",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/San-Francisco",
+    "scope": "San Francisco California ocean region",
+    "region_key": "san_francisco",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_central",
+    "title": "CDFW Central Ocean Region",
+    "source_type": "cdfw_ocean_region_map",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Central",
+    "scope": "Central California ocean region",
+    "region_key": "central",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_southern",
+    "title": "CDFW Southern Ocean Region",
+    "source_type": "cdfw_ocean_region_map",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Southern",
+    "scope": "Southern California ocean region",
+    "region_key": "southern",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_region_san_francisco_bay",
+    "title": "CDFW San Francisco Bay Region",
+    "source_type": "cdfw_regional_regulations",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/SF-Bay",
+    "scope": "San Francisco Bay sport fishing region",
+    "region_key": "san_francisco_bay",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_groundfish_summary",
+    "title": "CDFW Groundfish Summary",
+    "source_type": "cdfw_species_regulations",
+    "url": "https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary",
+    "scope": "California ocean groundfish summaries",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdfw_crabs",
+    "title": "CDFW Crabs",
+    "source_type": "cdfw_species_regulations",
+    "url": "https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs",
+    "scope": "California ocean crab regulations",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdph_shellfish_advisories",
+    "title": "CDPH Shellfish Advisories",
+    "source_type": "cdph_shellfish_advisory",
+    "url": "https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx",
+    "scope": "California shellfish advisories",
+    "statewide_required": true,
+    "required_for_mvp": true
+  },
+  {
+    "id": "cdph_annual_mussel_quarantine",
+    "title": "CDPH Annual Mussel Quarantine",
+    "source_type": "cdph_annual_mussel_quarantine",
+    "url": "https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx",
+    "scope": "California annual mussel quarantine",
+    "statewide_required": true,
+    "required_for_mvp": true
+  }
+]

tests/fixtures/source-cache/.gitkeep

@@ -0,0 +1 @@
+

tests/fixtures/source-pages/.gitkeep

@@ -0,0 +1 @@
+

tests/test_source_extract.py

@@ -0,0 +1,46 @@
+"""Source extraction tests."""
+
+from coastwise.schemas import RefreshStatus, SourceSnapshot
+from coastwise.source_extract import (
+    content_hash,
+    default_structured_validation_set,
+    extract_structured_facts,
+    extract_source_chunks,
+    normalize_source_text,
+    tokenize_source_text,
+)
+from coastwise.source_cache import DEFAULT_SEED_CACHE_DIR, load_seed_cache
+
+
+def test_source_text_normalization_hashing_and_chunk_creation():
+    text = "<html><body><h1>Lingcod</h1><p>Minimum size: 22 inches total length.</p></body></html>"
+    normalized = normalize_source_text(text)
+
+    assert normalized == "Lingcod Minimum size: 22 inches total length."
+    assert content_hash(normalized) == content_hash("Lingcod Minimum size: 22 inches total length.")
+    assert "lingcod" in tokenize_source_text(normalized)
+
+    snapshot = SourceSnapshot(
+        source_id="cdfw_ocean",
+        url="https://wildlife.ca.gov/Fishing/Ocean/Regulations",
+        title="CDFW Ocean Sport Fishing",
+        retrieved_at="2026-06-14T12:00:00+00:00",
+        content_hash=content_hash(normalized),
+        raw_text=normalized,
+        origin="seed",
+        refresh_status=RefreshStatus.UNCHANGED,
+    )
+    chunks = extract_source_chunks(snapshot)
+
+    assert chunks
+    assert chunks[0].source_url == snapshot.url
+    assert "lingcod" in chunks[0].tokens
+
+
+def test_extract_structured_validation_set_facts_from_seed_chunks():
+    cache = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+    result = extract_structured_facts(cache.chunks, default_structured_validation_set())
+    fact_ids = {fact.id for fact in result.facts}
+
+    assert {"lingcod_min_size", "lingcod_bag_limit", "dungeness_crab_bag_limit"} <= fact_ids
+    assert not result.issues

tests/test_source_refresh.py

@@ -0,0 +1,32 @@
+"""Source refresh tests."""
+
+from datetime import datetime, timezone
+
+from coastwise.schemas import RefreshStatus
+from coastwise.source_cache import DEFAULT_SEED_CACHE_DIR, load_seed_cache
+from coastwise.source_refresh import refresh_official_sources
+from coastwise.source_registry import load_official_sources
+
+
+NOW = datetime(2026, 6, 14, 13, tzinfo=timezone.utc)
+
+
+def test_refresh_official_sources_reports_updated_unchanged_failed_and_partial():
+    sources = load_official_sources()[:3]
+    cache = load_seed_cache(DEFAULT_SEED_CACHE_DIR)
+
+    def fetcher(source):
+        if source.id == sources[0].id:
+            return cache.snapshots_by_source_id[source.id].raw_text + " updated"
+        if source.id == sources[1].id:
+            return cache.snapshots_by_source_id[source.id].raw_text
+        raise OSError("network unavailable")
+
+    result, refreshed_cache = refresh_official_sources(sources, cache, NOW, fetcher)
+
+    assert result.source_results[sources[0].id] is RefreshStatus.UPDATED
+    assert result.source_results[sources[1].id] is RefreshStatus.UNCHANGED
+    assert result.source_results[sources[2].id] is RefreshStatus.FAILED
+    assert sources[2].id in result.cache_preserved_source_ids
+    assert refreshed_cache.snapshots_by_source_id[sources[2].id].content_hash
+    assert "failed" in result.user_message.lower()

tests/test_source_registry.py

@@ -0,0 +1,38 @@
+"""Source registry tests."""
+
+from coastwise.source_registry import (
+    load_official_sources,
+    statewide_source_coverage,
+    validate_source_registry,
+)
+
+
+def test_source_registry_uses_official_https_urls_only():
+    sources = load_official_sources()
+    issues = validate_source_registry(sources)
+
+    assert sources
+    assert not [issue for issue in issues if issue.severity == "error"]
+    for source in sources:
+        assert source.url.startswith("https://")
+        assert "wildlife.ca.gov" in source.url or "cdph.ca.gov" in source.url
+
+
+def test_statewide_registry_includes_required_regions_and_cdph_sources():
+    sources = load_official_sources()
+    source_ids = {source.id for source in sources}
+    coverage = statewide_source_coverage()
+
+    assert {
+        "northern",
+        "mendocino",
+        "san_francisco",
+        "central",
+        "southern",
+        "san_francisco_bay",
+    } <= set(coverage.required_region_keys)
+    assert set(coverage.required_source_ids) <= source_ids
+    assert "cdfw_inseason_changes" in coverage.general_source_ids
+    assert {"cdph_shellfish_advisories", "cdph_annual_mussel_quarantine"} <= set(
+        coverage.cdph_source_ids
+    )