Ai Research Explore

display_name: Rigor Explore
short_description: Rigor Explore compatible slug for candidate-only current_research exploration into auditable explore_outputs.
default_prompt: Use current_research as the explicit exploratory context, coordinate isolated code and run exploration conservatively, treat novelty as a hypothesis until evidence supports it, and write CHANGESET.md TOP_RUNS.md and status.json into explore_outputs.

"""Internal lookup helpers for ai-research-explore."""

from .cache_store import load_cache_index, store_records
from .inventory_writer import write_source_inventory, write_sources_summary
from .normalizers import detect_locator, ensure_http_url
from .repo_extractors import extract_repo_local_seeds
from .source_support import build_source_support, write_source_support

__all__ = [
    "build_source_support",
    "detect_locator",
    "ensure_http_url",
    "extract_repo_local_seeds",
    "load_cache_index",
    "store_records",
    "write_source_inventory",
    "write_source_support",
    "write_sources_summary",
]

"""Cache/index helpers for source records."""

from __future__ import annotations

import json
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, Iterable, List

from .normalizers import slugify, stable_digest, stable_filename
from .record_schema import normalize_record, record_priority


def _normalized_id_from_index_item(item: Dict[str, Any]) -> str:
    if item.get("normalized_id"):
        return str(item.get("normalized_id"))
    provider_type = str(item.get("provider_type") or "seed")
    identifier = str(item.get("provider_identifier") or item.get("source_url") or item.get("query") or "")
    return f"{provider_type}:{identifier}".strip(":")


def load_cache_index(sources_dir: Path) -> Dict[str, Any]:
    index_path = sources_dir / "index.json"
    if not index_path.exists():
        return {
            "schema_version": "2.0",
            "mode": "free-first-cache-first",
            "records_dir": "sources/records",
            "records": [],
            "record_lookup": {},
        }
    payload = json.loads(index_path.read_text(encoding="utf-8"))
    records = payload.get("records", [])
    payload["record_lookup"] = {
        _normalized_id_from_index_item(item): dict(item)
        for item in records
        if _normalized_id_from_index_item(item)
    }
    return payload


def _merge_lists(left: Iterable[Any], right: Iterable[Any]) -> List[Any]:
    merged: List[Any] = []
    for item in list(left) + list(right):
        if item not in merged and item not in ("", None, []):
            merged.append(item)
    return merged


def _prefer_value(existing: Any, incoming: Any) -> Any:
    if incoming not in ("", None, [], {}):
        return incoming
    return existing


def merge_records(existing: Dict[str, Any], incoming: Dict[str, Any]) -> Dict[str, Any]:
    normalized_existing = normalize_record(existing)
    normalized_incoming = normalize_record(incoming)
    if record_priority(normalized_incoming) >= record_priority(normalized_existing):
        primary, secondary = normalized_incoming, normalized_existing
    else:
        primary, secondary = normalized_existing, normalized_incoming
    merged = dict(primary)
    for key in (
        "title",
        "summary",
        "url",
        "venue",
        "repo_full_name",
        "doi",
        "arxiv_id",
        "source_repo",
        "source_file",
        "source_symbol",
    ):
        merged[key] = _prefer_value(secondary.get(key), primary.get(key))
    merged["authors"] = _merge_lists(secondary.get("authors", []), primary.get("authors", []))
    merged["origins"] = _merge_lists(secondary.get("origins", []), primary.get("origins", []))
    merged["extracted_from_repo_paths"] = _merge_lists(
        secondary.get("extracted_from_repo_paths", []),
        primary.get("extracted_from_repo_paths", []),
    )
    merged["selection_hints"] = _merge_lists(secondary.get("selection_hints", []), primary.get("selection_hints", []))
    merged["provider_metadata"] = {**secondary.get("provider_metadata", {}), **primary.get("provider_metadata", {})}
    return normalize_record(merged)


def store_records(sources_dir: Path, records: Iterable[Dict[str, Any]]) -> Dict[str, Any]:
    sources_dir.mkdir(parents=True, exist_ok=True)
    records_dir = sources_dir / "records"
    records_dir.mkdir(parents=True, exist_ok=True)

    existing_index = load_cache_index(sources_dir)
    existing_lookup = existing_index.get("record_lookup", {})
    stored_by_id: Dict[str, Dict[str, Any]] = {}
    cache_hits = 0
    cache_misses = 0
    merge_upgrades = 0

    for raw_record in records:
        record = normalize_record(raw_record)
        normalized_id = str(record.get("normalized_id") or "")
        if not normalized_id:
            identity = {
                "source_type": record.get("source_type"),
                "provider_type": record.get("provider_type"),
                "locator_type": record.get("locator_type"),
                "raw_locator": record.get("raw_locator"),
                "url": record.get("url"),
                "title": record.get("title"),
            }
            normalized_id = f"seed:{stable_digest(identity)[:16]}"
            record["normalized_id"] = normalized_id
        if normalized_id in stored_by_id:
            stored_by_id[normalized_id] = merge_records(stored_by_id[normalized_id], record)
            continue
        existing = existing_lookup.get(normalized_id)
        if existing:
            cache_hits += 1
            existing_rel = str(existing.get("artifact_path") or "")
            existing_path = None
            if existing_rel.startswith("sources/"):
                existing_path = sources_dir / Path(existing_rel).relative_to("sources")
            existing_payload = dict(existing)
            if existing_path and existing_path.exists():
                existing_payload = json.loads(existing_path.read_text(encoding="utf-8"))
            merged = merge_records(existing_payload, record)
            if record_priority(merged) > record_priority(normalize_record(existing_payload)):
                merge_upgrades += 1
            merged["cache_hit"] = True
            stored_by_id[normalized_id] = merged
        else:
            cache_misses += 1
            record["cache_hit"] = False
            stored_by_id[normalized_id] = record

    timestamp = datetime.now(timezone.utc).isoformat()
    stored_records: List[Dict[str, Any]] = []
    index_records: List[Dict[str, Any]] = []
    for normalized_id in sorted(stored_by_id):
        record = normalize_record(stored_by_id[normalized_id])
        if not record.get("resolved_at"):
            record["resolved_at"] = timestamp
        digest = stable_digest(
            {
                "normalized_id": normalized_id,
                "provider_type": record.get("provider_type"),
                "source_type": record.get("source_type"),
            }
        )
        source_id = record.get("source_id") or f"{record.get('source_type', 'source')}:{digest[:8]}"
        record["source_id"] = source_id
        slug = slugify(record.get("title") or normalized_id)
        filename = stable_filename(str(record.get("source_type") or "source"), slug, digest)
        artifact_path = records_dir / filename
        record["artifact_path"] = f"sources/records/{filename}"
        record["artifact_abspath"] = str(artifact_path)
        record["digest"] = digest
        artifact_path.write_text(
            json.dumps({"schema_version": "2.0", **record}, indent=2, ensure_ascii=False),
            encoding="utf-8",
        )
        stored_records.append(record)
        index_records.append(
            {
                "source_id": source_id,
                "source_type": record.get("source_type"),
                "provider_type": record.get("provider_type"),
                "locator_type": record.get("locator_type"),
                "raw_locator": record.get("raw_locator"),
                "normalized_id": normalized_id,
                "title": record.get("title"),
                "url": record.get("url"),
                "repo_full_name": record.get("repo_full_name"),
                "doi": record.get("doi"),
                "arxiv_id": record.get("arxiv_id"),
                "evidence_class": record.get("evidence_class"),
                "evidence_weight": record.get("evidence_weight"),
                "parse_status": record.get("parse_status"),
                "cache_hit": record.get("cache_hit"),
                "artifact_path": record.get("artifact_path"),
                "source_repo": record.get("source_repo"),
                "source_file": record.get("source_file"),
                "source_symbol": record.get("source_symbol"),
                "resolved_at": record.get("resolved_at"),
            }
        )

    index_payload = {
        "schema_version": "2.0",
        "mode": "free-first-cache-first",
        "records_dir": "sources/records",
        "records": index_records,
        "stats": {
            "record_count": len(index_records),
            "cache_hits": cache_hits,
            "cache_misses": cache_misses,
            "merge_upgrades": merge_upgrades,
        },
    }
    index_path = sources_dir / "index.json"
    index_path.write_text(json.dumps(index_payload, indent=2, ensure_ascii=False), encoding="utf-8")
    return {
        "index_path": str(index_path),
        "records_dir": str(records_dir),
        "records": stored_records,
        "cache_hits": cache_hits,
        "cache_misses": cache_misses,
        "merge_upgrades": merge_upgrades,
    }

"""Human-readable lookup inventory writers."""

from __future__ import annotations

from pathlib import Path
from typing import Any, Dict, Sequence


def write_sources_summary(sources_dir: Path, records: Sequence[Dict[str, Any]]) -> Path:
    lines = [
        "# Sources Summary",
        "",
        "Research lookup for `ai-research-explore` is free-first, cache-first, and auditable.",
        "",
        "## Cached Records",
        "",
    ]
    if not records:
        lines.append("- None.")
    else:
        for item in records:
            triple = " / ".join(
                part
                for part in [
                    str(item.get("source_repo") or ""),
                    str(item.get("source_file") or ""),
                    str(item.get("source_symbol") or ""),
                ]
                if part
            ) or "no-source-triple"
            lines.append(
                f"- `{item.get('source_id')}` `{item.get('provider_type')}` `{item.get('title')}` -> `{item.get('artifact_path')}` evidence={item.get('evidence_class', 'unknown')} triple={triple}"
            )
    summary_path = sources_dir / "SUMMARY.md"
    summary_path.write_text("\n".join(lines), encoding="utf-8")
    return summary_path


def write_source_inventory(
    analysis_output_dir: Path,
    *,
    records: Sequence[Dict[str, Any]],
    repo_local_extractions: Sequence[Dict[str, Any]],
    cache_stats: Dict[str, Any],
) -> Path:
    by_class: Dict[str, int] = {}
    for item in records:
        key = str(item.get("evidence_class") or "unknown")
        by_class[key] = by_class.get(key, 0) + 1
    lines = [
        "# Source Inventory",
        "",
        "Human-readable inventory for free-first, provider-optional research lookup.",
        "",
        "## Evidence Breakdown",
        "",
    ]
    if by_class:
        for key in sorted(by_class):
            lines.append(f"- `{key}`: {by_class[key]}")
    else:
        lines.append("- None.")
    lines.extend(
        [
            "",
            "## Cache Stats",
            "",
            f"- Cache hits: {cache_stats.get('cache_hits', 0)}",
            f"- Cache misses: {cache_stats.get('cache_misses', 0)}",
            f"- Merge upgrades: {cache_stats.get('merge_upgrades', 0)}",
            "",
            "## Repo-local Extractions",
            "",
        ]
    )
    if repo_local_extractions:
        for item in repo_local_extractions[:20]:
            paths = ", ".join(item.get("extracted_from_repo_paths", [])) or "unknown-path"
            lines.append(f"- `{item.get('raw_locator') or item.get('query')}` from `{paths}`")
    else:
        lines.append("- None.")
    lines.extend(["", "## Resolved Records", ""])
    if records:
        for item in records:
            lines.append(
                f"- `{item.get('source_id')}` `{item.get('source_type')}` `{item.get('provider_type')}` `{item.get('title')}` evidence=`{item.get('evidence_class')}`"
            )
    else:
        lines.append("- None.")
    path = analysis_output_dir / "SOURCE_INVENTORY.md"
    path.write_text("\n".join(lines), encoding="utf-8")
    return path

"""Locator parsing and normalization helpers for research lookup."""

from __future__ import annotations

import hashlib
import json
import re
import urllib.parse
from typing import Any, Dict, Optional


ARXIV_ID_RE = re.compile(r"(?:arxiv:|arxiv\.org/(?:abs|pdf)/)?(?P<id>\d{4}\.\d{4,5}(?:v\d+)?)", re.IGNORECASE)
DOI_RE = re.compile(r"(?:https?://(?:dx\.)?doi\.org/)?(?P<doi>10\.\d{4,9}/[-._;()/:A-Z0-9]+)", re.IGNORECASE)
GITHUB_URL_RE = re.compile(
    r"^https?://github\.com/(?P<owner>[^/\s]+)/(?P<repo>[^/\s#]+)(?:/(?P<rest>.*))?$",
    re.IGNORECASE,
)
HTTP_URL_RE = re.compile(r"^https?://", re.IGNORECASE)
URL_RE = re.compile(r"https?://[^\s<>\]\"')]+", re.IGNORECASE)


def slugify(value: str) -> str:
    slug = re.sub(r"[^a-z0-9]+", "-", str(value).lower()).strip("-")
    return slug[:48] or "source"


def stable_digest(payload: Dict[str, Any]) -> str:
    text = json.dumps(payload, sort_keys=True, ensure_ascii=False)
    return hashlib.sha1(text.encode("utf-8")).hexdigest()


def stable_filename(kind: str, slug: str, digest: str, suffix: str = "json") -> str:
    return f"{kind}__{slug}__{digest[:12]}.{suffix}"


def ensure_http_url(value: str) -> str:
    text = str(value or "").strip()
    if not text:
        return ""
    if HTTP_URL_RE.match(text):
        return text
    if text.lower().startswith("doi:"):
        return f"https://doi.org/{text[4:].strip()}"
    return text


def canonicalize_url(value: str) -> str:
    text = ensure_http_url(value)
    if not text:
        return ""
    parsed = urllib.parse.urlsplit(text)
    path = parsed.path or "/"
    return urllib.parse.urlunsplit(
        (
            parsed.scheme.lower(),
            parsed.netloc.lower(),
            path.rstrip("/") or "/",
            parsed.query,
            "",
        )
    )


def extract_urls(text: str) -> list[str]:
    found: list[str] = []
    for match in URL_RE.finditer(str(text or "")):
        url = match.group(0).rstrip(".,);]")
        if url not in found:
            found.append(url)
    return found


def parse_arxiv_locator(locator: str) -> Optional[Dict[str, Any]]:
    text = str(locator or "").strip()
    match = ARXIV_ID_RE.search(text)
    if not match:
        return None
    arxiv_id = match.group("id")
    locator_type = "arxiv_url" if "arxiv.org" in text.lower() else "arxiv_id"
    return {
        "provider_type": "arxiv",
        "source_type": "paper",
        "locator_type": locator_type,
        "raw_locator": text,
        "normalized_id": f"arxiv:{arxiv_id.lower()}",
        "identifier": arxiv_id,
        "arxiv_id": arxiv_id,
        "url": f"https://arxiv.org/abs/{arxiv_id}",
    }


def parse_doi_locator(locator: str) -> Optional[Dict[str, Any]]:
    text = str(locator or "").strip()
    match = DOI_RE.search(text)
    if not match:
        return None
    doi = match.group("doi").lower()
    locator_type = "doi_url" if "doi.org" in text.lower() else "doi"
    return {
        "provider_type": "doi",
        "source_type": "paper",
        "locator_type": locator_type,
        "raw_locator": text,
        "normalized_id": f"doi:{doi}",
        "identifier": doi,
        "doi": doi,
        "url": f"https://doi.org/{doi}",
    }


def parse_github_repo_locator(locator: str) -> Optional[Dict[str, Any]]:
    text = canonicalize_url(locator)
    match = GITHUB_URL_RE.match(text)
    if not match:
        return None
    owner = match.group("owner")
    repo = (match.group("repo") or "").removesuffix(".git")
    rest = match.group("rest") or ""
    source_file = ""
    if rest.startswith("blob/"):
        parts = rest.split("/", 3)
        if len(parts) == 4:
            source_file = parts[3]
    return {
        "provider_type": "github",
        "source_type": "repo",
        "locator_type": "github_repo_url",
        "raw_locator": str(locator or "").strip(),
        "normalized_id": f"github:{owner.lower()}/{repo.lower()}",
        "identifier": f"{owner}/{repo}",
        "repo_full_name": f"{owner}/{repo}",
        "owner": owner,
        "repo": repo,
        "source_file": source_file,
        "url": f"https://github.com/{owner}/{repo}",
    }


def parse_generic_url(locator: str) -> Optional[Dict[str, Any]]:
    text = canonicalize_url(locator)
    if not HTTP_URL_RE.match(text):
        return None
    parsed = urllib.parse.urlsplit(text)
    return {
        "provider_type": "url",
        "source_type": "web",
        "locator_type": "url",
        "raw_locator": str(locator or "").strip(),
        "normalized_id": f"url:{text}",
        "identifier": text,
        "host": parsed.netloc.lower(),
        "url": text,
    }


def detect_locator(locator: str) -> Optional[Dict[str, Any]]:
    for parser in (parse_github_repo_locator, parse_arxiv_locator, parse_doi_locator, parse_generic_url):
        parsed = parser(locator)
        if parsed:
            return parsed
    return None

"""Provider adapters for free-first research lookup."""

from .arxiv_provider import resolve_arxiv_record
from .doi_provider import resolve_doi_record
from .github_provider import resolve_github_record
from .optional_provider import resolve_optional_record
from .url_provider import resolve_url_record

__all__ = [
    "resolve_arxiv_record",
    "resolve_doi_record",
    "resolve_github_record",
    "resolve_optional_record",
    "resolve_url_record",
]

"""Free arXiv metadata provider."""

from __future__ import annotations

import urllib.parse
import xml.etree.ElementTree as ET
from typing import Any, Dict

from .base import http_get


def resolve_arxiv_record(locator_info: Dict[str, Any]) -> Dict[str, Any]:
    arxiv_id = str(locator_info.get("arxiv_id") or locator_info.get("identifier") or "").strip()
    record = {
        "provider_type": "arxiv",
        "source_type": "paper",
        "locator_type": locator_info.get("locator_type", "arxiv_id"),
        "raw_locator": locator_info.get("raw_locator", ""),
        "normalized_id": locator_info.get("normalized_id", f"arxiv:{arxiv_id.lower()}"),
        "title": f"arXiv:{arxiv_id}" if arxiv_id else "",
        "url": locator_info.get("url", ""),
        "authors": [],
        "year": None,
        "venue": "arXiv",
        "doi": "",
        "arxiv_id": arxiv_id,
        "parse_status": "parsed-only",
        "fetch_status": "parsed-only",
        "evidence_class": "parsed_locator",
        "provider_metadata": {"resolved_via": "arxiv"},
    }
    if not arxiv_id:
        return record
    try:
        payload = http_get(
            f"https://export.arxiv.org/api/query?id_list={urllib.parse.quote(arxiv_id)}",
            accept="application/atom+xml, text/xml;q=0.9",
        )
        root = ET.fromstring(payload.decode("utf-8", errors="ignore"))
        namespace = {"atom": "http://www.w3.org/2005/Atom"}
        entry = root.find("atom:entry", namespace)
        if entry is None:
            return {**record, "parse_status": "fetch-failed", "fetch_status": "fetch-failed"}
        authors = [
            (node.findtext("atom:name", default="", namespaces=namespace) or "").strip()
            for node in entry.findall("atom:author", namespace)
            if (node.findtext("atom:name", default="", namespaces=namespace) or "").strip()
        ]
        published = (entry.findtext("atom:published", default="", namespaces=namespace) or "").strip()
        year = int(published[:4]) if published[:4].isdigit() else None
        url = record["url"]
        for item in entry.findall("atom:link", namespace):
            href = item.attrib.get("href", "")
            if href:
                url = href
                break
        return {
            **record,
            "title": (entry.findtext("atom:title", default="", namespaces=namespace) or "").strip() or record["title"],
            "summary": (entry.findtext("atom:summary", default="", namespaces=namespace) or "").strip(),
            "authors": authors,
            "year": year,
            "url": url,
            "parse_status": "resolved",
            "fetch_status": "network-fetched",
            "evidence_class": "external_provider",
        }
    except Exception:
        return {**record, "parse_status": "fetch-failed", "fetch_status": "fetch-failed"}

"""Shared transport and HTML helpers for lookup providers."""

from __future__ import annotations

import json
import urllib.request
from html.parser import HTMLParser
from typing import Any, Dict, List, Optional, Tuple


REQUEST_TIMEOUT_SECONDS = 6
USER_AGENT = "ai-research-explore-lookup/2.0"


class MetadataHTMLParser(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.in_title = False
        self.title_parts: List[str] = []
        self.meta: Dict[str, str] = {}
        self.links: Dict[str, str] = {}

    def handle_starttag(self, tag: str, attrs: List[Tuple[str, Optional[str]]]) -> None:
        lowered = tag.lower()
        attr_map = {key.lower(): (value or "") for key, value in attrs}
        if lowered == "title":
            self.in_title = True
        if lowered == "meta":
            name = attr_map.get("name") or attr_map.get("property")
            content = attr_map.get("content", "").strip()
            if name and content:
                self.meta[name.lower()] = content
        if lowered == "link":
            rel = attr_map.get("rel", "").lower()
            href = attr_map.get("href", "").strip()
            if rel and href:
                self.links[rel] = href

    def handle_endtag(self, tag: str) -> None:
        if tag.lower() == "title":
            self.in_title = False

    def handle_data(self, data: str) -> None:
        if self.in_title and data.strip():
            self.title_parts.append(data.strip())

    def title_text(self) -> str:
        return " ".join(self.title_parts).strip()

    def description_text(self) -> str:
        for key in ("og:description", "description", "twitter:description"):
            if self.meta.get(key):
                return self.meta[key]
        return ""

    def canonical_url(self) -> str:
        return self.links.get("canonical") or self.meta.get("og:url", "")


def http_get(url: str, *, accept: str = "application/json, text/plain;q=0.9, text/html;q=0.8") -> bytes:
    request = urllib.request.Request(
        url,
        headers={
            "User-Agent": USER_AGENT,
            "Accept": accept,
        },
    )
    with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
        return response.read()


def http_get_json(url: str, *, accept: str = "application/json") -> Dict[str, Any]:
    payload = http_get(url, accept=accept)
    loaded = json.loads(payload.decode("utf-8", errors="ignore"))
    return loaded if isinstance(loaded, dict) else {}


def coerce_author_list(values: Any) -> List[str]:
    authors: List[str] = []
    if isinstance(values, list):
        for item in values:
            if isinstance(item, dict):
                given = str(item.get("given") or "").strip()
                family = str(item.get("family") or "").strip()
                full = " ".join(part for part in [given, family] if part).strip()
                if full:
                    authors.append(full)
            elif str(item).strip():
                authors.append(str(item).strip())
    return authors

"""Free DOI metadata provider."""

from __future__ import annotations

import json
import urllib.parse
from typing import Any, Dict

from .base import coerce_author_list, http_get


def resolve_doi_record(locator_info: Dict[str, Any]) -> Dict[str, Any]:
    doi = str(locator_info.get("doi") or locator_info.get("identifier") or "").strip().lower()
    record = {
        "provider_type": "doi",
        "source_type": "paper",
        "locator_type": locator_info.get("locator_type", "doi"),
        "raw_locator": locator_info.get("raw_locator", ""),
        "normalized_id": locator_info.get("normalized_id", f"doi:{doi}"),
        "title": f"DOI:{doi}" if doi else "",
        "url": locator_info.get("url", f"https://doi.org/{doi}" if doi else ""),
        "authors": [],
        "year": None,
        "venue": "",
        "doi": doi,
        "arxiv_id": "",
        "parse_status": "parsed-only",
        "fetch_status": "parsed-only",
        "evidence_class": "parsed_locator",
        "provider_metadata": {"resolved_via": "doi"},
    }
    if not doi:
        return record
    try:
        payload = http_get(
            f"https://doi.org/{urllib.parse.quote(doi, safe='/')}",
            accept="application/vnd.citationstyles.csl+json, application/json;q=0.9",
        )
        loaded = json.loads(payload.decode("utf-8", errors="ignore"))
        title = loaded.get("title")
        if isinstance(title, list):
            title = title[0] if title else ""
        venue = loaded.get("container-title")
        if isinstance(venue, list):
            venue = venue[0] if venue else ""
        year = None
        issued = loaded.get("issued") or {}
        date_parts = issued.get("date-parts") if isinstance(issued, dict) else None
        if isinstance(date_parts, list) and date_parts and isinstance(date_parts[0], list) and date_parts[0]:
            value = date_parts[0][0]
            year = int(value) if isinstance(value, int) or (isinstance(value, str) and str(value).isdigit()) else None
        return {
            **record,
            "title": str(title or record["title"]),
            "summary": str(loaded.get("abstract") or ""),
            "authors": coerce_author_list(loaded.get("author")),
            "year": year,
            "venue": str(venue or loaded.get("publisher") or ""),
            "url": str(loaded.get("URL") or record["url"]),
            "parse_status": "resolved",
            "fetch_status": "network-fetched",
            "evidence_class": "external_provider",
            "provider_metadata": {
                "resolved_via": "doi",
                "publisher": loaded.get("publisher"),
                "type": loaded.get("type"),
            },
        }
    except Exception:
        return {**record, "parse_status": "fetch-failed", "fetch_status": "fetch-failed"}

"""Free GitHub repository metadata provider."""

from __future__ import annotations

import base64
from typing import Any, Dict, List

from lookup.normalizers import extract_urls

from .base import http_get_json


def _paper_links(links: List[str]) -> List[str]:
    return [
        link
        for link in links
        if "arxiv.org" in link.lower() or "doi.org" in link.lower() or "openreview.net" in link.lower()
    ]


def _fetch_readme(owner: str, repo: str) -> Dict[str, Any]:
    try:
        payload = http_get_json(f"https://api.github.com/repos/{owner}/{repo}/readme")
    except Exception:
        return {"readme_links": [], "paper_links_in_readme": []}
    content = payload.get("content")
    if not content:
        return {"readme_links": [], "paper_links_in_readme": []}
    try:
        decoded = base64.b64decode(str(content).encode("utf-8"), validate=False).decode("utf-8", errors="ignore")
    except Exception:
        return {"readme_links": [], "paper_links_in_readme": []}
    links = extract_urls(decoded)
    return {
        "readme_links": links,
        "paper_links_in_readme": _paper_links(links),
    }


def resolve_github_record(locator_info: Dict[str, Any]) -> Dict[str, Any]:
    repo_full_name = str(locator_info.get("repo_full_name") or locator_info.get("identifier") or "").strip()
    owner = str(locator_info.get("owner") or "").strip()
    repo = str(locator_info.get("repo") or "").strip()
    record = {
        "provider_type": "github",
        "source_type": "repo",
        "locator_type": locator_info.get("locator_type", "github_repo_url"),
        "raw_locator": locator_info.get("raw_locator", ""),
        "normalized_id": locator_info.get("normalized_id", f"github:{repo_full_name.lower()}"),
        "title": repo_full_name,
        "url": locator_info.get("url", ""),
        "authors": [],
        "year": None,
        "venue": "GitHub",
        "repo_full_name": repo_full_name,
        "doi": "",
        "arxiv_id": "",
        "source_file": locator_info.get("source_file", ""),
        "parse_status": "parsed-only",
        "fetch_status": "parsed-only",
        "evidence_class": "parsed_locator",
        "provider_metadata": {"resolved_via": "github"},
    }
    if not owner or not repo:
        return record
    try:
        payload = http_get_json(f"https://api.github.com/repos/{owner}/{repo}")
        readme_meta = _fetch_readme(owner, repo)
        return {
            **record,
            "title": str(payload.get("full_name") or record["title"]),
            "summary": str(payload.get("description") or ""),
            "url": str(payload.get("html_url") or record["url"]),
            "repo_full_name": str(payload.get("full_name") or repo_full_name),
            "parse_status": "resolved",
            "fetch_status": "network-fetched",
            "evidence_class": "external_provider",
            "provider_metadata": {
                "resolved_via": "github",
                "default_branch": payload.get("default_branch"),
                "homepage": payload.get("homepage"),
                "license": (payload.get("license") or {}).get("spdx_id"),
                "stargazers_count": payload.get("stargazers_count"),
                **readme_meta,
            },
        }
    except Exception:
        return {**record, "parse_status": "fetch-failed", "fetch_status": "fetch-failed"}

"""Optional paid-provider adapter placeholder."""

from __future__ import annotations

import os
from typing import Any, Dict, Optional


OPTIONAL_PROVIDER_ENV_VARS = {
    "openrouter": "RESEARCH_LOOKUP_OPENROUTER_API_KEY",
    "perplexity": "RESEARCH_LOOKUP_PERPLEXITY_API_KEY",
    "parallel": "RESEARCH_LOOKUP_PARALLEL_API_KEY",
}


def resolve_optional_record(locator_info: Dict[str, Any], lookup_config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
    configured = lookup_config.get("optional_providers") if isinstance(lookup_config, dict) else None
    providers = [str(item).strip().lower() for item in (configured or []) if str(item).strip()]
    for provider_name in providers:
        env_name = OPTIONAL_PROVIDER_ENV_VARS.get(provider_name)
        if env_name and os.environ.get(env_name):
            return None
    return None

"""Generic URL metadata provider."""

from __future__ import annotations

import urllib.parse
from typing import Any, Dict

from lookup.normalizers import canonicalize_url

from .base import MetadataHTMLParser, http_get


def resolve_url_record(locator_info: Dict[str, Any]) -> Dict[str, Any]:
    url = canonicalize_url(locator_info.get("url") or locator_info.get("raw_locator") or "")
    parsed = urllib.parse.urlsplit(url) if url else None
    record = {
        "provider_type": "url",
        "source_type": "web",
        "locator_type": locator_info.get("locator_type", "url"),
        "raw_locator": locator_info.get("raw_locator", ""),
        "normalized_id": locator_info.get("normalized_id", f"url:{url}" if url else ""),
        "title": url,
        "url": url,
        "authors": [],
        "year": None,
        "venue": parsed.netloc if parsed else "",
        "repo_full_name": "",
        "doi": "",
        "arxiv_id": "",
        "parse_status": "parsed-only",
        "fetch_status": "parsed-only",
        "evidence_class": "parsed_locator",
        "provider_metadata": {"resolved_via": "url", "host": parsed.netloc.lower() if parsed else ""},
    }
    if not url:
        return record
    try:
        payload = http_get(url, accept="text/html, application/xhtml+xml;q=0.9")
        parser = MetadataHTMLParser()
        parser.feed(payload.decode("utf-8", errors="ignore"))
        canonical = parser.canonical_url() or url
        return {
            **record,
            "title": parser.meta.get("og:title") or parser.title_text() or url,
            "summary": parser.description_text(),
            "url": canonicalize_url(canonical),
            "parse_status": "resolved",
            "fetch_status": "network-fetched",
            "evidence_class": "external_provider",
            "provider_metadata": {
                **record["provider_metadata"],
                "canonical_url": canonicalize_url(canonical),
            },
        }
    except Exception:
        return {**record, "parse_status": "fetch-failed", "fetch_status": "fetch-failed"}

"""Lookup record schema helpers."""

from __future__ import annotations

from typing import Any, Dict


EVIDENCE_CLASS_ALIASES = {
    "external-provider": "external_provider",
    "parsed-locator": "parsed_locator",
    "repo-local-extracted": "repo_local_extracted",
    "seed-only": "seed_only",
}

EVIDENCE_CLASS_PRIORITY = {
    "seed_only": 0,
    "repo_local_extracted": 1,
    "parsed_locator": 2,
    "external_provider": 3,
}

DEFAULT_RECORD_FIELDS = {
    "source_type": "web",
    "provider_type": "seed",
    "locator_type": "seed",
    "raw_locator": "",
    "normalized_id": "",
    "title": "",
    "summary": "",
    "url": "",
    "authors": [],
    "year": None,
    "venue": "",
    "repo_full_name": "",
    "doi": "",
    "arxiv_id": "",
    "evidence_class": "seed_only",
    "evidence_weight": 0.2,
    "resolved_at": "",
    "cache_hit": False,
    "parse_status": "seed-only",
    "fetch_status": "seed-only",
    "provider_metadata": {},
    "source_repo": "",
    "source_file": "",
    "source_symbol": "",
    "origins": [],
    "extracted_from_repo_paths": [],
    "selection_hints": [],
}


def normalize_evidence_class(value: Any, default: str = "seed_only") -> str:
    text = str(value or "").strip().lower().replace("-", "_")
    text = EVIDENCE_CLASS_ALIASES.get(text, text)
    if text in EVIDENCE_CLASS_PRIORITY:
        return text
    return default


def evidence_weight_for_class(evidence_class: Any, parse_status: Any = "") -> float:
    normalized = normalize_evidence_class(evidence_class)
    status = str(parse_status or "").strip().lower()
    if normalized == "external_provider":
        return 1.0 if status in {"resolved", "network-fetched"} else 0.9
    if normalized == "parsed_locator":
        return 0.65
    if normalized == "repo_local_extracted":
        return 0.45
    return 0.2


def metadata_completeness(record: Dict[str, Any]) -> int:
    score = 0
    for key in ("title", "summary", "url", "repo_full_name", "doi", "arxiv_id", "venue"):
        if record.get(key):
            score += 1
    authors = record.get("authors")
    if isinstance(authors, list) and authors:
        score += 1
    if record.get("year"):
        score += 1
    return score


def normalize_record(record: Dict[str, Any]) -> Dict[str, Any]:
    normalized = {**DEFAULT_RECORD_FIELDS, **record}
    normalized["evidence_class"] = normalize_evidence_class(normalized.get("evidence_class"))
    normalized["evidence_weight"] = round(
        float(
            normalized.get("evidence_weight")
            or evidence_weight_for_class(normalized["evidence_class"], normalized.get("parse_status"))
        ),
        4,
    )
    normalized["authors"] = [str(item) for item in normalized.get("authors", []) if str(item).strip()]
    normalized["origins"] = [str(item) for item in normalized.get("origins", []) if str(item).strip()]
    normalized["extracted_from_repo_paths"] = [
        str(item).replace("\\", "/")
        for item in normalized.get("extracted_from_repo_paths", [])
        if str(item).strip()
    ]
    normalized["selection_hints"] = [str(item) for item in normalized.get("selection_hints", []) if str(item).strip()]
    return normalized


def record_priority(record: Dict[str, Any]) -> tuple[int, int]:
    normalized = normalize_record(record)
    return (
        EVIDENCE_CLASS_PRIORITY.get(normalized["evidence_class"], 0),
        metadata_completeness(normalized),
    )

"""Repo-local source extraction for free-first research lookup."""

from __future__ import annotations

from pathlib import Path
from typing import Any, Dict, List

from .normalizers import ARXIV_ID_RE, DOI_RE, detect_locator, extract_urls


IGNORED_DIRS = {
    ".git",
    ".venv",
    "__pycache__",
    "node_modules",
    "dist",
    "build",
    ".mypy_cache",
    ".pytest_cache",
}


def _candidate_paths(repo_path: Path) -> List[Path]:
    patterns = [
        "README*",
        "*.md",
        "*.rst",
        "*.yaml",
        "*.yml",
        "*.toml",
        "*.ini",
        "*.py",
    ]
    results: List[Path] = []
    seen: set[Path] = set()
    for pattern in patterns:
        for path in repo_path.rglob(pattern):
            if not path.is_file():
                continue
            if any(part in IGNORED_DIRS for part in path.relative_to(repo_path).parts):
                continue
            if path.stat().st_size > 256_000:
                continue
            if path in seen:
                continue
            seen.add(path)
            results.append(path)
    return sorted(results)[:120]


def _extract_locators(text: str) -> List[str]:
    found: List[str] = []
    for url in extract_urls(text):
        if url not in found:
            found.append(url)
    for pattern in (ARXIV_ID_RE, DOI_RE):
        for match in pattern.finditer(text):
            raw = match.group(0).strip()
            if raw and raw not in found:
                found.append(raw)
    return found


def _classify_kind(locator: str) -> str:
    parsed = detect_locator(locator)
    if not parsed:
        return "web"
    source_type = parsed.get("source_type")
    if source_type in {"paper", "repo", "web"}:
        return str(source_type)
    return "web"


def extract_repo_local_seeds(repo_path: Path) -> List[Dict[str, Any]]:
    repo_root = Path(repo_path).resolve()
    seeds: List[Dict[str, Any]] = []
    seen_locators: set[str] = set()
    for path in _candidate_paths(repo_root):
        try:
            text = path.read_text(encoding="utf-8", errors="ignore")
        except OSError:
            continue
        locators = _extract_locators(text)
        relative_path = path.relative_to(repo_root).as_posix()
        for locator in locators:
            if locator in seen_locators:
                continue
            seen_locators.add(locator)
            seeds.append(
                {
                    "kind": _classify_kind(locator),
                    "title": locator,
                    "summary": f"Repo-local extracted source from `{relative_path}`.",
                    "query": locator,
                    "source_url": locator if locator.lower().startswith("http") else "",
                    "source_repo": "",
                    "source_file": "",
                    "source_symbol": "",
                    "origin": "repo_local_extracted",
                    "raw_locator": locator,
                    "extracted_from_repo_paths": [relative_path],
                }
            )
    return seeds

"""Machine-readable source support artifacts for downstream passes."""

from __future__ import annotations

import json
import re
from pathlib import Path
from typing import Any, Dict, List, Sequence

from .record_schema import normalize_evidence_class


def _tokenize(value: Any) -> List[str]:
    return [token for token in re.split(r"[^a-z0-9]+", str(value or "").lower()) if len(token) > 2]


def _record_haystack(record: Dict[str, Any]) -> str:
    return " ".join(
        [
            str(record.get("title") or ""),
            str(record.get("summary") or ""),
            str(record.get("url") or ""),
            str(record.get("repo_full_name") or ""),
            str(record.get("doi") or ""),
            str(record.get("arxiv_id") or ""),
            str(record.get("source_repo") or ""),
            str(record.get("source_file") or ""),
            str(record.get("source_symbol") or ""),
        ]
    ).lower()


def _match_records(tokens: Sequence[str], records: Sequence[Dict[str, Any]]) -> List[Dict[str, Any]]:
    matches: List[tuple[int, float, Dict[str, Any]]] = []
    for record in records:
        haystack = _record_haystack(record)
        score = sum(1 for token in tokens if token in haystack)
        if score > 0:
            matches.append((score, float(record.get("evidence_weight") or 0.0), record))
    matches.sort(key=lambda item: (-item[0], -item[1], item[2].get("source_id", "")))
    return [record for _score, _weight, record in matches[:6]]


def build_source_support(
    campaign: Dict[str, Any],
    records: Sequence[Dict[str, Any]],
    repo_local_extractions: Sequence[Dict[str, Any]],
    cache_stats: Dict[str, Any],
) -> Dict[str, Any]:
    by_evidence_class: Dict[str, List[str]] = {}
    by_type: Dict[str, List[str]] = {}
    for item in records:
        evidence = normalize_evidence_class(item.get("evidence_class"))
        by_evidence_class.setdefault(evidence, []).append(str(item.get("source_id")))
        source_type = str(item.get("source_type") or "unknown")
        by_type.setdefault(source_type, []).append(str(item.get("source_id")))

    support_index_by_candidate_idea: Dict[str, Dict[str, Any]] = {}
    support_index_by_target_component: Dict[str, Dict[str, Any]] = {}
    for idea in campaign.get("candidate_ideas", []):
        idea_id = str(idea.get("id") or "idea")
        tokens = _tokenize(idea.get("summary")) + _tokenize(idea.get("target_component")) + _tokenize(idea.get("change_scope"))
        matched = _match_records(tokens, records)
        support_index_by_candidate_idea[idea_id] = {
            "matched_source_ids": [item.get("source_id") for item in matched],
            "matched_external_source_ids": [
                item.get("source_id")
                for item in matched
                if normalize_evidence_class(item.get("evidence_class")) == "external_provider"
            ],
            "matched_repo_local_source_ids": [
                item.get("source_id")
                for item in matched
                if normalize_evidence_class(item.get("evidence_class")) == "repo_local_extracted"
            ],
            "matched_parsed_locator_ids": [
                item.get("source_id")
                for item in matched
                if normalize_evidence_class(item.get("evidence_class")) == "parsed_locator"
            ],
        }
        component = str(idea.get("target_component") or "unspecified")
        support_index_by_target_component.setdefault(component, {"matched_source_ids": []})
        for source_id in support_index_by_candidate_idea[idea_id]["matched_source_ids"]:
            if source_id not in support_index_by_target_component[component]["matched_source_ids"]:
                support_index_by_target_component[component]["matched_source_ids"].append(source_id)

    return {
        "schema_version": "1.0",
        "records": list(records),
        "records_by_evidence_class": by_evidence_class,
        "records_by_type": by_type,
        "support_index_by_candidate_idea": support_index_by_candidate_idea,
        "support_index_by_target_component": support_index_by_target_component,
        "repo_local_extractions": list(repo_local_extractions),
        "cache_stats": cache_stats,
    }


def write_source_support(analysis_output_dir: Path, support_bundle: Dict[str, Any]) -> Path:
    path = analysis_output_dir / "SOURCE_SUPPORT.json"
    path.write_text(json.dumps(support_bundle, indent=2, ensure_ascii=False), encoding="utf-8")
    return path

"""Internal passes for ai-research-explore orchestration."""

from .atomic_idea_decomposition import run_atomic_idea_decomposition_pass
from .candidate_idea_generation import run_candidate_idea_generation_pass
from .execution_feasibility import run_execution_feasibility_pass
from .idea_cards import run_idea_card_pass
from .idea_ranking import run_idea_ranking_pass
from .implementation_fidelity import run_implementation_fidelity_pass
from .improvement_bank import run_improvement_bank_pass
from .lookup_sources import run_lookup_pass
from .source_mapping import run_source_mapping_pass

__all__ = [
    "run_atomic_idea_decomposition_pass",
    "run_candidate_idea_generation_pass",
    "run_execution_feasibility_pass",
    "run_idea_card_pass",
    "run_idea_ranking_pass",
    "run_implementation_fidelity_pass",
    "run_improvement_bank_pass",
    "run_lookup_pass",
    "run_source_mapping_pass",
]

"""Atomic academic concept decomposition for ai-research-explore."""

from __future__ import annotations

import json
import re
from pathlib import Path
from typing import Any, Dict, List, Sequence


BLOCKED_SCOPES = {"unspecified", "broad_rewrite", "rewrite-everything"}


def tokenize(value: Any) -> List[str]:
    return [token for token in re.split(r"[^a-z0-9]+", str(value or "").lower()) if len(token) > 2]


def unique_preserving(values: Sequence[str], *, limit: int | None = None) -> List[str]:
    ordered: List[str] = []
    for value in values:
        if not value or value in ordered:
            continue
        ordered.append(value)
        if limit is not None and len(ordered) >= limit:
            break
    return ordered


def humanize_slug(value: str) -> str:
    text = str(value or "").replace("_", " ").replace("-", " ").strip()
    return " ".join(part.capitalize() for part in text.split()) or "Atomic Concept"


def classify_surface(path: str) -> str:
    lowered = str(path).lower()
    if any(token in lowered for token in ("config", ".yaml", ".yml", ".json", ".toml", ".ini")):
        return "config"
    if any(token in lowered for token in ("data", "dataset", "loader", "transform")):
        return "data interface"
    if any(token in lowered for token in ("eval", "metric", "benchmark", "validation", "test")):
        return "evaluation adapter"
    if any(token in lowered for token in ("train", "trainer", "loss", "optim", "schedule")):
        return "training"
    return "model"


def formula_support(selected_idea: Dict[str, Any], lookup_bundle: Dict[str, Any]) -> List[Dict[str, Any]]:
    source_ids = list(selected_idea.get("source_reference", []) or [])
    records = {item.get("source_id"): item for item in lookup_bundle.get("records", []) if item.get("source_id")}
    support: List[Dict[str, Any]] = []
    for source_id in source_ids[:3]:
        record = records.get(source_id) or {}
        support.append(
            {
                "source_id": source_id,
                "title": record.get("title") or "Unresolved source reference",
                "evidence_class": record.get("evidence_class") or "unresolved",
                "note": "Use this source only as bounded academic support; it is not a novelty proof.",
            }
        )
    if not support:
        support.append(
            {
                "source_id": "none",
                "title": "No directly matched formula-level source",
                "evidence_class": "none",
                "note": "Concept remains grounded in repo-local constraints rather than directly verified source material.",
            }
        )
    return support


def code_support(selected_idea: Dict[str, Any], source_mapping: Dict[str, Any]) -> List[Dict[str, Any]]:
    selected_source = source_mapping.get("selected_source_record", {}) or {}
    target_location_map = source_mapping.get("target_location_map", []) or []
    support: List[Dict[str, Any]] = []
    if selected_source:
        support.append(
            {
                "source_id": selected_source.get("source_id") or "selected-source-record",
                "source_repo": selected_source.get("source_repo") or "",
                "source_file": selected_source.get("source_file") or "",
                "source_symbol": selected_source.get("source_symbol") or "",
                "note": "Candidate source triple for a bounded transplant or adaptation path.",
            }
        )
    if target_location_map:
        support.append(
            {
                "source_id": "repo-local-target-map",
                "source_repo": "current-research",
                "source_file": target_location_map[0].get("file") or "",
                "source_symbol": target_location_map[0].get("target_symbol") or "",
                "note": "Repo-local implementation target inferred from source mapping.",
            }
        )
    if not support:
        support.append(
            {
                "source_id": "none",
                "source_repo": "current-research",
                "source_file": "",
                "source_symbol": "",
                "note": "No concrete code support could be resolved.",
            }
        )
    return support


def unit_validation_strategy(surface: str, selected_idea: Dict[str, Any], variant_spec: Dict[str, Any]) -> str:
    if surface == "config":
        return f"Verify that `{selected_idea.get('change_scope', 'candidate change')}` can be isolated through config or CLI overrides without touching the frozen eval contract."
    if surface == "evaluation adapter":
        return "Keep evaluation surfaces protected; validate only compatibility and do not change metric semantics."
    if variant_spec.get("base_command"):
        return f"Smoke the implementation through `{variant_spec['base_command']}` with a short-run gate before any broader candidate run."
    return "Use a bounded static and short-run validation path before claiming the idea is implementable."


def implementation_risk(selected_idea: Dict[str, Any], surface: str) -> float:
    base = float(selected_idea.get("implementation_risk") or 0.4)
    if surface in {"training", "evaluation adapter"}:
        base += 0.10
    return max(0.0, min(1.0, round(base, 4)))


def scientific_meaning_risk(selected_idea: Dict[str, Any], surface: str) -> float:
    base = float(selected_idea.get("eval_risk") or 0.3)
    if surface == "evaluation adapter":
        base += 0.20
    if surface == "training":
        base += 0.10
    return max(0.0, min(1.0, round(base, 4)))


def build_atomic_units(
    *,
    selected_idea: Dict[str, Any],
    analysis_data: Dict[str, Any],
    source_mapping: Dict[str, Any],
    lookup_bundle: Dict[str, Any],
    variant_spec: Dict[str, Any],
) -> tuple[List[Dict[str, Any]], List[str]]:
    blockers: List[str] = []
    change_scope = str(selected_idea.get("change_scope") or "unspecified")
    target_component = str(selected_idea.get("target_component") or "unspecified")
    if change_scope in BLOCKED_SCOPES:
        blockers.append("selected-idea-change-scope-too-broad-for-atomic-decomposition")
    target_location_map = source_mapping.get("target_location_map", []) or []
    module_candidates = source_mapping.get("module_candidates", []) or []
    if not target_location_map and not module_candidates:
        blockers.append("no-target-surface-for-atomic-decomposition")

    code_files = unique_preserving(
        [
            str(item.get("file") or "")
            for item in target_location_map
            if str(item.get("role") or "") == "code"
        ]
        + [str(item.get("target_file") or "") for item in module_candidates],
        limit=5,
    )
    config_files = unique_preserving(
        [
            str(item.get("file") or "")
            for item in target_location_map
            if str(item.get("role") or "") == "config"
        ]
        + list(analysis_data.get("config_binding_hints", [])),
        limit=4,
    )
    code_symbols = unique_preserving(
        [str(item.get("target_symbol") or "") for item in target_location_map if item.get("target_symbol")]
        + list(analysis_data.get("constructor_candidates", []))
        + list(analysis_data.get("forward_candidates", [])),
        limit=6,
    )

    units: List[Dict[str, Any]] = []
    if code_files:
        surface = classify_surface(code_files[0])
        units.append(
            {
                "atomic_id": f"{selected_idea.get('id', 'idea')}-atomic-01",
                "concept_name": humanize_slug(change_scope or target_component),
                "concept_summary": str(selected_idea.get("summary") or "Bounded implementation concept"),
                "why_needed": f"Translate the selected idea into repo-local `{surface}` logic without broad architectural rewrites.",
                "formula_support": formula_support(selected_idea, lookup_bundle),
                "code_support": code_support(selected_idea, source_mapping),
                "expected_code_surface": surface,
                "target_file_candidates": code_files,
                "target_symbol_candidates": code_symbols or unique_preserving([target_component], limit=3),
                "validation_strategy": unit_validation_strategy(surface, selected_idea, variant_spec),
                "implementation_risk": implementation_risk(selected_idea, surface),
                "scientific_meaning_risk": scientific_meaning_risk(selected_idea, surface),
            }
        )
    if config_files:
        units.append(
            {
                "atomic_id": f"{selected_idea.get('id', 'idea')}-atomic-02",
                "concept_name": f"{humanize_slug(change_scope)} Control Surface",
                "concept_summary": f"Expose `{change_scope}` as a single-variable ablation surface rather than an entangled rewrite.",
                "why_needed": "Keep attribution clear, rollback easy, and short-run feasibility auditable.",
                "formula_support": formula_support(selected_idea, lookup_bundle),
                "code_support": code_support(selected_idea, source_mapping),
                "expected_code_surface": "config",
                "target_file_candidates": config_files,
                "target_symbol_candidates": unique_preserving(
                    list(analysis_data.get("config_binding_hints", [])) + [change_scope, target_component],
                    limit=6,
                ),
                "validation_strategy": unit_validation_strategy("config", selected_idea, variant_spec),
                "implementation_risk": implementation_risk(selected_idea, "config"),
                "scientific_meaning_risk": scientific_meaning_risk(selected_idea, "config"),
            }
        )

    if not units:
        blockers.append("selected-idea-could-not-be-split-into-implementable-atomic-units")
    return units, unique_preserving(blockers)


def write_atomic_markdown(output_dir: Path, payload: Dict[str, Any]) -> Path:
    lines = [
        "# Atomic Idea Map",
        "",
        f"- Status: `{payload.get('status', 'blocked')}`",
        f"- Selected idea: `{payload.get('selected_idea_id', 'none')}`",
        "",
        "## Blockers",
        "",
    ]
    blockers = payload.get("blockers", [])
    if blockers:
        lines.extend(f"- {item}" for item in blockers)
    else:
        lines.append("- None.")
    lines.extend(["", "## Atomic Units", ""])
    atomic_units = payload.get("atomic_units", [])
    if not atomic_units:
        lines.append("- None.")
    else:
        for unit in atomic_units:
            lines.extend(
                [
                    f"### {unit['atomic_id']} - {unit['concept_name']}",
                    "",
                    f"- Summary: {unit['concept_summary']}",
                    f"- Why needed: {unit['why_needed']}",
                    f"- Expected code surface: `{unit['expected_code_surface']}`",
                    f"- Target file candidates: {', '.join(unit.get('target_file_candidates', [])) or 'none'}",
                    f"- Target symbol candidates: {', '.join(unit.get('target_symbol_candidates', [])) or 'none'}",
                    f"- Validation strategy: {unit['validation_strategy']}",
                    f"- Implementation risk: `{unit['implementation_risk']}`",
                    f"- Scientific meaning risk: `{unit['scientific_meaning_risk']}`",
                    "",
                ]
            )
    path = output_dir / "ATOMIC_IDEA_MAP.md"
    path.write_text("\n".join(lines), encoding="utf-8")
    return path


def run_atomic_idea_decomposition_pass(
    *,
    analysis_output_dir: Path,
    selected_idea: Dict[str, Any],
    analysis_data: Dict[str, Any],
    source_mapping: Dict[str, Any],
    lookup_bundle: Dict[str, Any],
    current_research: str,
    variant_spec: Dict[str, Any],
) -> Dict[str, Any]:
    del current_research
    atomic_units, blockers = build_atomic_units(
        selected_idea=selected_idea,
        analysis_data=analysis_data,
        source_mapping=source_mapping,
        lookup_bundle=lookup_bundle,
        variant_spec=variant_spec,
    )
    payload = {
        "schema_version": "1.0",
        "status": "blocked" if blockers else "ready",
        "selected_idea_id": str(selected_idea.get("id") or ""),
        "atomic_units": atomic_units,
        "atomic_unit_count": len(atomic_units),
        "blockers": blockers,
    }
    json_path = analysis_output_dir / "ATOMIC_IDEA_MAP.json"
    json_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
    markdown_path = write_atomic_markdown(analysis_output_dir, payload)
    return {
        **payload,
        "artifact_paths": [str(markdown_path), str(json_path)],
        "artifact_path": str(json_path),
    }