doiget-core 0.4.0

//! Dry-run preview shape for `--dry-run` CLI fetches and the
//! `doiget_metadata_only` / `doiget_fetch_paper` MCP tools.
//!
//! Binding spec: [`docs/DECISIONS/0022-dry-run-mode.md`](../../../docs/DECISIONS/0022-dry-run-mode.md)
//! §1 (NORMATIVE wire shape) and [`docs/MCP_TOOLS.md`](../../../docs/MCP_TOOLS.md)
//! §10 (MCP envelope mirror).
//!
//! The types here live in `doiget-core` rather than `doiget-cli` so that
//! both `doiget-cli` (the `--dry-run` flag path) and `doiget-mcp` (the
//! `dry_run: true` tool variants) can serialize bit-identical envelopes
//! without `doiget-mcp` having to depend on `doiget-cli` (which would
//! invert the existing `doiget-cli -> doiget-mcp` wiring).
//!
//! ## Honesty about candidate uncertainty
//!
//! The `pdf_sources[].candidate_hosts` list is the **static allowlist**
//! for the named resolver, not the host the actual fetch would have hit.
//! doiget cannot know the post-Unpaywall OA URL host without making the
//! Unpaywall network call, and `--dry-run` MUST NOT make it. The preview
//! is therefore an *upper-bound* on the hosts a real fetch could touch,
//! not a prediction of the single host it would touch (ADR-0022 §4).

use camino::{Utf8Path, Utf8PathBuf};
use serde::Serialize;

use crate::http::{oa_publisher_allowlist, tier_1_allowlist, SourceAllowlist};
use crate::source::FetchError;
use crate::{RateLimits, Ref};

/// Per-PDF-source row inside [`FetchPlan::pdf_sources`].
///
/// `candidate_hosts` is the static allowlist for the named resolver, not
/// a prediction of the single host the real fetch would touch — see
/// [module docs](self) and ADR-0022 §4 ("Honesty about candidate
/// uncertainty").
#[derive(Debug, Clone, Serialize)]
pub struct PdfSourcePlan {
    /// Resolver source key (e.g. `"oa-publisher"`, `"arxiv"`).
    pub key: String,
    /// Allowlist hosts the real fetch would be permitted to touch.
    pub candidate_hosts: Vec<String>,
}

/// Per-process rate-limit context surfaced alongside [`FetchPlan`] so an
/// agent can predict the politeness ceiling without a separate
/// `doiget_capability_profile` round-trip.
#[derive(Debug, Clone, Copy, Serialize)]
pub struct RateLimitBudget {
    /// Process-wide cap (matches [`RateLimits::HARD_CODED`]).
    pub global_per_sec: f32,
    /// Per-source minimum gap between consecutive requests, ms.
    pub per_source_min_gap_ms: u64,
}

/// Structured dry-run preview returned by `--dry-run` and the
/// `dry_run: true` MCP variants. Wire shape matches ADR-0022 §1 and
/// `docs/MCP_TOOLS.md` §10.
#[derive(Debug, Clone, Serialize)]
pub struct FetchPlan {
    /// Metadata sources the real fetch would consult, in dispatch order.
    pub metadata_sources: Vec<String>,
    /// PDF sources the real fetch could attempt. `candidate_hosts` is an
    /// upper-bound on the hosts a real fetch would touch (see
    /// [`PdfSourcePlan`]).
    pub pdf_sources: Vec<PdfSourcePlan>,
    /// Source keys whose redirect allowlists are loaded into the HTTP
    /// client. Useful for validating `CapabilityProfile` configuration
    /// drift.
    pub redirect_allowlists_loaded: Vec<String>,
    /// Where the PDF would land on disk (always `<root>/<safekey>.pdf`).
    pub target_pdf_path: Utf8PathBuf,
    /// Where the metadata TOML would land
    /// (always `<root>/.metadata/<safekey>.toml`).
    pub target_metadata_path: Utf8PathBuf,
    /// `true` in Phase 1+ — every successful fetch appends a provenance
    /// row. Named explicitly so future fetch modes can declare "this
    /// fetch would NOT append" without inverting the flag's meaning
    /// (ADR-0022 §1).
    pub would_append_provenance: bool,
    /// Always `true` in Phase 1: [`PdfSourcePlan::candidate_hosts`] is the
    /// **static allowlist** for the resolver, NOT a prediction of the
    /// single host the real fetch would touch. See ADR-0022 §4 ("Honesty
    /// about candidate uncertainty"). The field is machine-parseable so
    /// an agent can detect the upper-bound semantics without reading the
    /// spec — encoding the §4 disclaimer into the wire shape itself.
    pub candidate_hosts_are_upper_bound: bool,
}

/// Hard-coded rate-limit budget surfaced with every [`FetchPlan`] preview.
/// Mirrors [`RateLimits::HARD_CODED`] / `docs/LEGAL.md` §6 safeguard 8.
pub fn rate_limit_budget() -> RateLimitBudget {
    RateLimitBudget {
        global_per_sec: RateLimits::HARD_CODED.max_fetches_per_second(),
        per_source_min_gap_ms: RateLimits::HARD_CODED.per_source_backoff_ms(),
    }
}

/// Build the dry-run preview ([`FetchPlan`]) for the given ref and store
/// root, without contacting the network or filesystem.
///
/// Per-ref-kind shape (ADR-0022 §1, NORMATIVE):
///
/// - **DOI** → `metadata_sources = ["crossref", "unpaywall"]`,
///   `pdf_sources = [{ key: "oa-publisher", candidate_hosts: oa_publisher_allowlist hosts }]`.
/// - **arXiv** → `metadata_sources = []`,
///   `pdf_sources = [{ key: "arxiv", candidate_hosts: tier_1 arxiv hosts }]`.
///
/// `redirect_allowlists_loaded` always contains the four source keys the
/// production HTTP client is built with (Tier 1 + the synthetic OA
/// publisher), reflecting `doiget-cli::commands::fetch::build_http_client`'s
/// composition.
///
/// # Errors
///
/// This infallible-looking wrapper never returns `Err` — it delegates to
/// [`try_build_fetch_plan`] and, on the (should-be-impossible) internal
/// allowlist-contract drift, falls back to an empty `candidate_hosts`
/// list for the affected PDF source rather than panicking (issue #156 ②:
/// a stray `.expect()` here crashed `doiget plan` if a source key was
/// ever renamed). Callers that want to *observe* the invariant violation
/// as a typed error should call [`try_build_fetch_plan`] directly; this
/// function's signature is kept infallible because it is `pub` and has
/// non-`doiget-core` callers (`doiget-mcp`, `doiget-cli`) whose
/// signatures must not change in this batch.
///
/// The empty-`candidate_hosts` fallback is the lesser evil versus a
/// panic: a preview with an empty allowlist is visibly wrong (and is
/// what `try_build_fetch_plan` flags as `SourceSchema`), whereas a panic
/// takes down `doiget plan` entirely. This path is unreachable unless
/// [`oa_publisher_allowlist`] / [`tier_1_allowlist`] are edited to drop
/// the `"oa-publisher"` / `"arxiv"` keys, which the in-crate tests pin.
pub fn build_fetch_plan(ref_: &Ref, store_root: &Utf8Path) -> FetchPlan {
    try_build_fetch_plan(ref_, store_root).unwrap_or_else(|_| {
        // Internal-contract drift (allowlist key renamed): degrade to an
        // empty `candidate_hosts` instead of panicking `doiget plan`.
        // `try_build_fetch_plan` is the API that surfaces this as a
        // typed `FetchError::SourceSchema`.
        let safekey = ref_.safekey();
        let target_pdf_path = store_root.join(format!("{}.pdf", safekey.as_str()));
        let target_metadata_path = store_root
            .join(".metadata")
            .join(format!("{}.toml", safekey.as_str()));
        let (metadata_sources, pdf_key) = match ref_ {
            Ref::Doi(_) => (
                vec!["crossref".to_string(), "unpaywall".to_string()],
                "oa-publisher",
            ),
            Ref::Arxiv(_) => (Vec::<String>::new(), "arxiv"),
        };
        FetchPlan {
            metadata_sources,
            pdf_sources: vec![PdfSourcePlan {
                key: pdf_key.to_string(),
                candidate_hosts: Vec::new(),
            }],
            redirect_allowlists_loaded: tier_1_allowlist()
                .iter()
                .chain(oa_publisher_allowlist().iter())
                .map(|a| a.source.clone())
                .collect(),
            target_pdf_path,
            target_metadata_path,
            would_append_provenance: true,
            candidate_hosts_are_upper_bound: true,
        }
    })
}

/// Fallible builder for the dry-run preview ([`FetchPlan`]).
///
/// Identical to [`build_fetch_plan`] on the happy path, but propagates an
/// internal allowlist-contract drift as a typed
/// [`FetchError::SourceSchema`] (which maps to
/// [`crate::ErrorCode::InternalError`] at the public boundary — the
/// correct closed-set fit for an internal-invariant violation) instead
/// of panicking. This is the API issue #156 ② asks for; it is added
/// alongside the existing infallible [`build_fetch_plan`] rather than
/// replacing it, because `build_fetch_plan` is `pub` and called from
/// `doiget-mcp` / `doiget-cli`, whose signatures are out of scope for
/// this change batch.
///
/// # Errors
///
/// Returns [`FetchError::SourceSchema`] if the in-crate allowlist
/// builders ([`oa_publisher_allowlist`] / [`tier_1_allowlist`]) stop
/// returning the `"oa-publisher"` / `"arxiv"` source keys this function
/// looks up — an internal-contract drift bug, surfaced rather than
/// panicked (issue #156 ②). The in-crate tests pin the keys so this is
/// unreachable in a correct build.
pub fn try_build_fetch_plan(ref_: &Ref, store_root: &Utf8Path) -> Result<FetchPlan, FetchError> {
    let safekey = ref_.safekey();
    let target_pdf_path = store_root.join(format!("{}.pdf", safekey.as_str()));
    let target_metadata_path = store_root
        .join(".metadata")
        .join(format!("{}.toml", safekey.as_str()));

    let (metadata_sources, pdf_sources) = match ref_ {
        Ref::Doi(_) => {
            // Internal contract: `oa_publisher_allowlist()` MUST always
            // return an entry whose `.source == "oa-publisher"`. A silent
            // `.unwrap_or_default()` here would mask drift between this
            // function and the allowlist source-of-truth — the resulting
            // empty `candidate_hosts` would mislead an agent into
            // believing the OA leg has no allowed hosts. Issue #156 ②:
            // surface the drift as a typed error rather than `.expect()`
            // panicking `doiget plan`.
            let oa_hosts = oa_publisher_allowlist()
                .into_iter()
                .find(|a: &SourceAllowlist| a.source == "oa-publisher")
                .map(|a| a.redirect_hosts)
                .ok_or_else(|| FetchError::SourceSchema {
                    hint: "internal-contract drift: oa-publisher allowlist \
                           missing (see crates/doiget-core/src/http.rs::\
                           oa_publisher_allowlist); build_fetch_plan and \
                           oa_publisher_allowlist have drifted"
                        .to_string(),
                })?;
            (
                vec!["crossref".to_string(), "unpaywall".to_string()],
                vec![PdfSourcePlan {
                    key: "oa-publisher".to_string(),
                    candidate_hosts: oa_hosts,
                }],
            )
        }
        Ref::Arxiv(_) => {
            // Same internal-contract rationale as the DOI branch above.
            let arxiv_hosts = tier_1_allowlist()
                .into_iter()
                .find(|a: &SourceAllowlist| a.source == "arxiv")
                .map(|a| a.redirect_hosts)
                .ok_or_else(|| FetchError::SourceSchema {
                    hint: "internal-contract drift: tier-1 allowlist missing \
                           'arxiv' (see crates/doiget-core/src/http.rs::\
                           tier_1_allowlist); build_fetch_plan and \
                           tier_1_allowlist have drifted"
                        .to_string(),
                })?;
            (
                Vec::<String>::new(),
                vec![PdfSourcePlan {
                    key: "arxiv".to_string(),
                    candidate_hosts: arxiv_hosts,
                }],
            )
        }
    };

    // Slice 5 (PR #84 advisory item A6): derive the loaded-allowlist
    // list from the same `tier_1_allowlist()` + `oa_publisher_allowlist()`
    // functions the production `HttpClient` is composed from. A
    // hardcoded `vec![...]` here would silently drift if a future slice
    // adds a new allowlist source to the production client — the wire
    // shape would still claim only the old four.
    let redirect_allowlists_loaded: Vec<String> = tier_1_allowlist()
        .iter()
        .chain(oa_publisher_allowlist().iter())
        .map(|a| a.source.clone())
        .collect();

    Ok(FetchPlan {
        metadata_sources,
        pdf_sources,
        redirect_allowlists_loaded,
        target_pdf_path,
        target_metadata_path,
        would_append_provenance: true,
        // Always `true` in Phase 1 per ADR-0022 §4 ("Honesty about
        // candidate uncertainty"): `candidate_hosts` is the static
        // resolver allowlist, NOT a prediction of the single host the
        // real fetch would touch. Surfaced on the wire so agents can
        // detect the upper-bound semantics without parsing the spec.
        candidate_hosts_are_upper_bound: true,
    })
}

/// Build the dry-run envelope as a `serde_json::Value`, without writing
/// anywhere. Used by both the CLI (which prints it to stdout) and the
/// MCP tool wrapper (which routes the bytes via JSON-RPC). Wire shape:
///
/// ```jsonc
/// {
///   "ok": true,
///   "dry_run": true,
///   "ref": { "doi": "10.1234/foo" } | { "arxiv": "2401.12345" },
///   "plan": { ... see FetchPlan ... },
///   "rate_limit_budget": { "global_per_sec": 5.0, "per_source_min_gap_ms": 200 }
/// }
/// ```
pub fn build_dry_run_envelope(ref_: &Ref, plan: &FetchPlan) -> serde_json::Value {
    serde_json::json!({
        "ok": true,
        "dry_run": true,
        "ref": ref_kind_object(ref_),
        "plan": plan,
        "rate_limit_budget": rate_limit_budget(),
    })
}

/// Build the `ref` field of the dry-run envelope per ADR-0022 §1:
/// `{"doi": "10.1234/foo"}` for a DOI ref, `{"arxiv": "2401.12345"}` for
/// an arXiv ref. We intentionally do NOT serialize the full `Ref` enum
/// (which would emit `{"kind":"doi","id":"10.1234/foo"}` per the
/// internally-tagged `#[serde(tag,content)]` form), because the wire
/// shape in the ADR uses a flat single-key object.
fn ref_kind_object(ref_: &Ref) -> serde_json::Value {
    match ref_ {
        Ref::Doi(d) => serde_json::json!({ "doi": d.as_str() }),
        Ref::Arxiv(a) => serde_json::json!({ "arxiv": a.as_str() }),
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod tests {
    use super::*;
    use crate::{ArxivId, Doi};

    fn temp_root() -> Utf8PathBuf {
        Utf8PathBuf::from("/tmp/doiget-test-store")
    }

    #[test]
    fn doi_plan_carries_crossref_and_unpaywall_metadata_sources() {
        let r = Ref::Doi(Doi("10.1234/example".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        assert_eq!(plan.metadata_sources, vec!["crossref", "unpaywall"]);
        assert_eq!(plan.pdf_sources.len(), 1);
        assert_eq!(plan.pdf_sources[0].key, "oa-publisher");
        assert!(
            !plan.pdf_sources[0].candidate_hosts.is_empty(),
            "OA publisher hosts must be populated"
        );
        assert!(plan.would_append_provenance);
    }

    #[test]
    fn arxiv_plan_has_empty_metadata_sources_and_arxiv_pdf_source() {
        let r = Ref::Arxiv(ArxivId("2401.12345".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        assert!(plan.metadata_sources.is_empty());
        assert_eq!(plan.pdf_sources.len(), 1);
        assert_eq!(plan.pdf_sources[0].key, "arxiv");
        assert!(plan.pdf_sources[0]
            .candidate_hosts
            .iter()
            .any(|h| h == "arxiv.org"));
    }

    #[test]
    fn plan_target_paths_are_safekey_derived() {
        let r = Ref::Doi(Doi("10.1234/example".to_string()));
        let root = Utf8PathBuf::from("/tmp/store");
        let plan = build_fetch_plan(&r, &root);
        assert_eq!(plan.target_pdf_path, root.join("doi_10.1234_example.pdf"));
        assert_eq!(
            plan.target_metadata_path,
            root.join(".metadata").join("doi_10.1234_example.toml")
        );
    }

    #[test]
    fn dry_run_envelope_has_top_level_ok_dry_run_and_rate_budget() {
        let r = Ref::Doi(Doi("10.1234/foo".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        let env = build_dry_run_envelope(&r, &plan);
        assert_eq!(env["ok"], serde_json::json!(true));
        assert_eq!(env["dry_run"], serde_json::json!(true));
        assert_eq!(env["ref"], serde_json::json!({ "doi": "10.1234/foo" }));
        assert_eq!(
            env["rate_limit_budget"]["global_per_sec"],
            serde_json::json!(5.0)
        );
        assert_eq!(
            env["rate_limit_budget"]["per_source_min_gap_ms"],
            serde_json::json!(200)
        );
    }

    #[test]
    fn dry_run_envelope_arxiv_ref_uses_arxiv_key() {
        let r = Ref::Arxiv(ArxivId("2401.12345".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        let env = build_dry_run_envelope(&r, &plan);
        assert_eq!(env["ref"], serde_json::json!({ "arxiv": "2401.12345" }));
    }

    #[test]
    fn fetch_plan_carries_candidate_hosts_are_upper_bound_true() {
        // ADR-0022 §4 ("Honesty about candidate uncertainty"): the field
        // is always `true` in Phase 1, and the wire envelope must
        // surface it inside `plan` so agents can detect the upper-bound
        // semantics without consulting the spec.
        let r = Ref::Doi(Doi("10.1234/example".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        assert!(plan.candidate_hosts_are_upper_bound);
        let env = build_dry_run_envelope(&r, &plan);
        assert_eq!(
            env["plan"]["candidate_hosts_are_upper_bound"],
            serde_json::json!(true),
            "plan.candidate_hosts_are_upper_bound must be true on the \
             wire (ADR-0022 §4); got: {env}"
        );
    }

    #[test]
    fn try_build_fetch_plan_ok_matches_build_fetch_plan() {
        // Issue #156 ②: the fallible variant must produce a plan
        // structurally identical to the infallible wrapper on the happy
        // path (the allowlist invariant holds in a correct build).
        for r in [
            Ref::Doi(Doi("10.1234/example".to_string())),
            Ref::Arxiv(ArxivId("2401.12345".to_string())),
        ] {
            let root = temp_root();
            let fallible = try_build_fetch_plan(&r, &root).expect("invariant holds");
            let infallible = build_fetch_plan(&r, &root);
            assert_eq!(fallible.metadata_sources, infallible.metadata_sources);
            assert_eq!(fallible.pdf_sources[0].key, infallible.pdf_sources[0].key);
            assert_eq!(
                fallible.pdf_sources[0].candidate_hosts,
                infallible.pdf_sources[0].candidate_hosts
            );
            assert!(
                !fallible.pdf_sources[0].candidate_hosts.is_empty(),
                "happy-path candidate_hosts must be populated, not the \
                 degraded empty fallback"
            );
        }
    }

    #[test]
    fn redirect_allowlists_loaded_lists_all_four_sources() {
        let r = Ref::Doi(Doi("10.1234/example".to_string()));
        let plan = build_fetch_plan(&r, &temp_root());
        // All four allowlist entries must be present (matches the
        // production `build_http_client` composition).
        assert_eq!(
            plan.redirect_allowlists_loaded,
            vec!["crossref", "unpaywall", "arxiv", "oa-publisher"]
        );
    }
}