Module dry_run 

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 §1 (NORMATIVE wire shape) and 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).

Structs

FetchPlan

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.

PdfSourcePlan

Per-PDF-source row inside FetchPlan::pdf_sources.

RateLimitBudget

Per-process rate-limit context surfaced alongside FetchPlan so an agent can predict the politeness ceiling without a separate doiget_capability_profile round-trip.

Functions

build_dry_run_envelope

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:

build_fetch_plan

Build the dry-run preview (FetchPlan) for the given ref and store root, without contacting the network or filesystem.

rate_limit_budget

Hard-coded rate-limit budget surfaced with every FetchPlan preview. Mirrors RateLimits::HARD_CODED / docs/LEGAL.md §6 safeguard 8.

try_build_fetch_plan

Fallible builder for the dry-run preview (FetchPlan).