[meta] Converged design v1.0 — final synthesis index

[sotashimozono]

Filed by Claude (Anthropic, AI agent operating under souta's GitHub auth) as a synthesis of all 18 prior Discussions and reviewer Decision proposals. Intended as the single-page snapshot of doiget's converged design before Phase 0 begins.

Status: PROPOSED Decision lock. Pending author final approval.

Purpose: If this repository is ever deleted (the author's stated worst-case), this single document, plus the ADRs in docs/DECISIONS/, must be sufficient to reconstruct every binding design decision. Treat it as the canonical synthesis.

---

0. Mission (one sentence)

doiget は、 user が 自ネットワーク内で読む権利を持つ 学術論文を、 公式 API 経由で安全に automate 取得する stdio MCP server + CLI である。 paywall を bypass せず、 host や share せず、 default で OA only。

---

1. Architecture

flowchart TB
    User[CLI user / Agent host]
    User --> CLI[doiget-cli<br/>fetch / batch / info / serve]
    CLI --> MCP[doiget-mcp<br/>stdio JSON-RPC, 9 tools]
    CLI --> Core[doiget-core]
    MCP --> Core

    Core --> Cap{CapabilityProfile<br/>oa / metadata / tdm-*}
    Cap -->|always on| OA[Tier 1 OA<br/>Crossref / Unpaywall / arXiv]
    Cap -->|opt-in env| Meta[Tier 2 metadata<br/>OpenAlex / S2 / DOAJ<br/>Phase 4]
    Cap -->|opt-in env + key + agree<br/>compile-time gated| TDM[Tier 3 TDM<br/>Springer OA / APS / Elsevier<br/>Phase 5a/5b/5c]

    OA --> Fetcher[Fetcher<br/>rate-cap 5/sec, size cap, redirect allowlist]
    Meta -.-> Fetcher
    TDM -.-> Fetcher

    Fetcher --> Log[Provenance Log<br/>JSON Lines + SHA256 hash chain<br/>fail-closed]
    Fetcher --> Store[Store<br/>~/papers/ + TOML metadata<br/>BiblioFetch.jl 互換]

    classDef hot fill:#fbb,stroke:#900
    classDef oa fill:#bfb,stroke:#060
    classDef gated fill:#fec,stroke:#a60
    class Cap hot
    class OA oa
    class TDM gated

Loading

---

2. Discussions index + Decision summary

#	Title	Reviewer Decision	Lock as ADR
1	BiblioFetch.jl 共存	A (side-by-side) + 4 contracts (schema / lock / atomic / safekey)	0004
2	Store compat	A → B with 5 規律 ([doiget] namespace / append-only / schema_version / reserved / normalize)	0004
3	MVP source	A (3 source = Crossref + Unpaywall + arXiv)、 parity は non-goal	0009
4	MCP transport	A (stdio only)、 HTTP は 永続的 non-goal	0001
5	TDM priority	Phase 5a/5b/5c 分割、 1-binary + opt-in build、 Phase 5 着手は production data 駆動	0002
6	Citation graph	A (Phase 4)、 hard-cap (depth=3, total=100, per-paper=20)、 cycle detection 必須	0010
7	Phase plan	MVP = 5 週 (改訂)、 Phase 5 skip 可、 Phase 順序: 0→1→2→3→3.5→4→5→6→7	0011
8	MCP tool spec	9 tools (6 + paper_pdf_path / capability_profile / health)、 snake_case + doiget_ prefix	0012
9	PDF 内容操作	A (Out of scope)、 Permanent non-goal	0003
10	CI/CD	9 workflow files (含 posture-lint / cross-tool-compat / safekey-vectors)、 OIDC / sigstore / SHA pin	0013
11	Docs strategy	A+C (Plain MD + rustdoc)、 NORMATIVE/INFORMATIVE 区分、 ADR 運用	0014
12	Threat model	5 + 5 threats (supply-chain / agent input / network side / log integrity / telemetry)、 cargo-vet 採用	0015
13	Common foundation	crate list 確定、 deny list、 Config = TOML + clap、 chrono UTC	0016
14	Personas / output	4 personas、 mode resolution flag>env>implicit>TTY>quiet、 EN-only	0017
15	Obsidian	C (export-on-demand)、 Phase 7 optional、 別 crate doiget-obsidian、 単方向 sync	0018
16	Legal posture	8 safeguards (5 social + 3 technical)、 jurisdictional caveat、 worst plausible case planning	0019
17	CapabilityProfile / log / safekey	NORMATIVE specs lock	0005 / 0006 / 0007
18	Crate decomposition	4 crate、 dependency 方向 enforce、 feature flag matrix	0008

---

3. Permanent non-goals (docs/SCOPE.md の予約 list)

doiget は 以下を恒久的に提供しない。 contributor PR で提案された場合は新 "scope reopening" Discussion を別途要求する meta-rule を CONTRIBUTING.md で明示。

1. PDF 内容処理 (extract / OCR / summarize / annotation) — [scope] PDF の内容操作 (extract / OCR / 要約) は in-scope か out-of-scope か #9
2. MCP HTTP / SSE / WebSocket transport — [design] MCP transport — stdio only or HTTP also #4
3. SaaS / hosted service (doiget.com 等) — [legal] Legal posture, tool neutrality framing, and required safeguards #16
4. Self-update / auto-update (doiget upgrade) — [security] threat model + security 対策 #12
5. Telemetry / phone-home / crash reporting — [security] threat model + security 対策 #12
6. 起動時 latest version check — [security] threat model + security 対策 #12
7. Anonymous usage statistics — [security] threat model + security 対策 #12
8. doiget_fetch_url(url: ...) MCP tool (SSRF surface) — [design] MCP server が公開する tool の名前と signature #8 / [security] threat model + security 対策 #12
9. doiget_set_credentials(...) MCP tool — [design] MCP server が公開する tool の名前と signature #8
10. doiget_delete_paper(...) MCP tool (agent 経由 destructive op) — [design] MCP server が公開する tool の名前と signature #8
11. Generic shell / exec MCP tool — [design] MCP server が公開する tool の名前と signature #8
12. Bulk download mode (秒数十件) — [legal] Legal posture, tool neutrality framing, and required safeguards #16
13. share-vault 機能 — [legal] Legal posture, tool neutrality framing, and required safeguards #16
14. Credential 共有機能 — [legal] Legal posture, tool neutrality framing, and required safeguards #16
15. tdm-all umbrella feature flag — [design] APS / Elsevier / Springer TDM の実装優先度 #5
16. 双方向 Obsidian sync — [integration] Obsidian backend として使いやすい設計 #15
17. Auto-discovery of Obsidian vault — [integration] Obsidian backend として使いやすい設計 #15

---

4. Phase 0 deliverable checklist

Phase 0 完了 = 以下を全て満たす。

Code

• Cargo workspace + 3 crates (doiget-core / doiget-cli / doiget-mcp)
• cargo build --features oa-only 成功 (default)
• doiget --help 動く (no subcommands)

Configuration

• Cargo.toml workspace + [features] matrix ([design] Cargo workspace の crate 分割と feature flag matrix #18)
• Cargo.lock commit
• rust-toolchain.toml (MSRV 1.83 pin)
• deny.toml (telemetry / HTTP server / openssl deny)
• .cargo/config.toml (build flags)
• clippy.toml (print_stdout deny in mcp crate)

NORMATIVE docs

• README.md ([legal] Legal posture, tool neutrality framing, and required safeguards #16 / [infra] ドキュメント整備の戦略 (README / docs/ / mdbook / rustdoc) #11)
• LICENSE (MIT)
• CONTACT.md (SLA / escalation / DMCA、 [legal] Legal posture, tool neutrality framing, and required safeguards #16 §7)
• docs/LEGAL.md ([legal] Legal posture, tool neutrality framing, and required safeguards #16 + jurisdictional caveat)
• docs/SCOPE.md (本 §3 の non-goal list)
• docs/SECURITY.md ([security] threat model + security 対策 #12 全 threat surface + supply-chain)
• docs/STORE.md (schema_version / flock / atomic write、 [design] BiblioFetch.jl との共存モデル #1 / [design] BiblioFetch.jl と TOML store の互換性レベル #2)
• docs/SAFEKEY.md (algorithm + 100 test vectors、 [design] CapabilityProfile + provenance log + safekey の normative spec #17)
• docs/CAPABILITY.md (CapabilityProfile spec、 [design] CapabilityProfile + provenance log + safekey の normative spec #17)
• docs/PROVENANCE_LOG.md (JSON Lines + hash chain、 [design] CapabilityProfile + provenance log + safekey の normative spec #17)
• docs/CONFIG.md (env var precedence、 [infra] 共通基盤 (logging / errors / config / test fixtures) #13)
• docs/PUBLIC_API.md (semver-locked Rust API、 [ux] User personas + 出力 mode 設計 (agent / researcher / CI / library) #14)
• docs/CACHE.md (resolver / citation cache、 [design] MCP server が公開する tool の名前と signature #8 / [design] Citation graph 機能を Phase 1 必須にするか後ろ倒しか #6)
• docs/ERRORS.md (persona × error code matrix、 [ux] User personas + 出力 mode 設計 (agent / researcher / CI / library) #14)
• CHANGELOG.md (Keep a Changelog format、 [infra] ドキュメント整備の戦略 (README / docs/ / mdbook / rustdoc) #11)

INFORMATIVE docs

• CONTRIBUTING.md (PR 規約、 doc style、 scope-reopening meta-rule)
• CODE_OF_CONDUCT.md
• docs/ARCHITECTURE.md (本 §1 の mermaid + module 図)
• docs/PHASES.md ([plan] Phase 計画と timeline #7)
• docs/MIGRATION.md (BiblioFetch.jl placeholder)
• docs/DECISIONS/INDEX.md + 19 ADR (0001-0019)

CI workflows

• ci.yml (lint / clippy / test、 9-job matrix)
• audit.yml (cargo audit + cargo deny)
• posture-lint.yml (禁止語 / HTTP server / telemetry deny)
• codeql.yml (Phase 0 から)
• safekey-vectors.yml (100 test vectors)
• cross-tool-compat.yml (Julia install + placeholder)
• dependabot.yml (auto-merge 無効、 minor/patch group)

Repo settings (manual)

• Branch protection on main (require PR review)
• 2FA required for author
• Signed commits required (tag.gpgsign = true、 commit signing)
• Action SHA pinning (existing actions を再 audit)

Test fixtures

• tests/fixtures/safekey/vectors.json (100 entries)
• tests/fixtures/golden/ placeholder

Pre-flight (#7 §5)

• BiblioFetch.jl 側の現行 safekey algorithm を確認、 [design] CapabilityProfile + provenance log + safekey の normative spec #17 spec に合わせて update if needed
• BiblioFetch.jl 現行 schema_version 確認
• crates.io trusted publishing 設定権限
• GitHub Environment 機能設定権限
• sigstore / cosign permissions

---

5. Numerical constants (hard-coded、 config で override 不可)

Constant	Value	Source
MAX_CONCURRENT_FETCHES	5	#16 §8
MAX_FETCHES_PER_SECOND	5.0	#16 §8
PER_SOURCE_BACKOFF_MS	200	#17
MCP_BATCH_MAX_SIZE	100	#8 §5 / #12
MCP_QUEUE_DEPTH_MAX	100	#4 §Backpressure
CITATION_GRAPH_MAX_DEPTH	3	#6 §1
CITATION_GRAPH_MAX_REFS_TOTAL	100	#6 §1
CITATION_GRAPH_MAX_REFS_PER_PAPER	20	#6 §1
RESOLVER_CACHE_TTL_DAYS	7	#8 §4
CITATION_CACHE_TTL_DAYS	30	#6 §5
LOG_RETENTION_DAYS_DEFAULT	90	#16 §5 / #17
LOG_FILE_ROTATE_BYTES	100_000_000	#17
MCP_STDIN_EOF_SHUTDOWN_SEC	5	#4
DOI_SUFFIX_MAX_LEN	256	#12 §threat 2
MSRV	1.83	#10 §4

---

6. MCP tool spec (確定 9 tools)

Tool	Phase	Description (1 行)
doiget_resolve_paper	3	DOI / arXiv id → metadata (Crossref + Unpaywall)
doiget_fetch_paper	3	DOI / arXiv id → PDF をローカル取得
doiget_batch_fetch	3	複数 ref を batch (max 100)
doiget_info	3	store 内 entry の metadata 取得
doiget_search_local	3	store 内全文 search (title / authors / venue)
doiget_list_recent	3	最近 fetch した N 件
doiget_paper_pdf_path	3	local PDF path のみ返す (内容 NOT touch)
doiget_capability_profile	3	この instance の capability を返す
doiget_health	3	operational sanity (store_writable / version)
doiget_expand_citation_graph	4	citation graph (depth/total/per-paper hard-cap)
doiget_bibtex_export	4	BibTeX 出力
doiget_csl_export	4	CSL JSON 出力

詳細は docs/MCP_TOOLS.md (Phase 3 で完成版)。

---

7. Risk posture summary (#16 統合)

• Probability: unknown (data-free)
• Worst plausible case: ¥100-300 万 (author affordable 上限)
• Plan against, not hope for: worst case を planning baseline、 risk math の確率は記載しない
• 8 safeguards (5 social + 3 technical):
  1. API key shipped 禁止
  2. Opt-in env var (TDM)
  3. README + SOURCES でユーザ責任明記
  4. CONTACT.md / takedown 受け皿 (SLA + escalation + DMCA)
  5. Marketing 言語 self-policing (CI guard)
  6. Compile-time feature gating (TDM 物理隔離)
  7. Runtime CapabilityProfile (hard-gate)
  8. Hard-coded rate limit

---

8. 進め方

1. 本 Discussion を author が approve したら、 各 ADR を docs/DECISIONS/ に commit する Phase 0 着手判断
2. Phase 0 の deliverable checklist を 1 つ ずつ満たす
3. 並列 agent dispatch ([plan] Phase 計画と timeline #7 §3) で docs と code を同時進行
4. Phase 0 完了 → Phase 1 (1.5 週) → Phase 2 (1 週) → Phase 3 (1.5 週) で MVP shipping point (5 週)
5. Phase 4 以降は MVP user feedback で着手判断

---

9. 残作業 (本 synthesis 後)

• author による本 Discussion の approve / 修正指示
• 1-18 の original Discussion を 使い捨て close (本 synthesis に Decision は集約済みなので、 個別 Discussion の保持は冗長)
• ADR 0001-0019 を docs/DECISIONS/ に commit (Phase 0 中)
• Pre-flight checklist の確認 ([plan] Phase 計画と timeline #7 §5)
• Phase 0 着手

---

Reviewer の確信度

私 (Claude as external reviewer) は、 本 synthesis が 完成版の design baseline として go できる 解像度に到達したと判断します。 個別 Discussion の reviewer Decision proposal は author の意思を尊重しつつ、 #16 posture 中心の整合性が全体で取れています。

但し以下は author 判断を待っている状態:

1. Phase 5 を skip する / production data 駆動で着手する / 完全延期 — どれを選ぶか
2. crate doiget-core の semver を 0.x 維持 vs Phase 6 で 1.0 — どちらか
3. 既存 16 Discussion を close するかどうか (本 synthesis で集約済みなので reviewer 推奨は close)

これらを author が確定すれば、 doiget の design phase は終了し、 Phase 0 着手に移れる状態です。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05. Final synthesis of 18 prior Discussions.