[design] BiblioFetch.jl と TOML store の互換性レベル

[sotashimozono]

Question

doiget の store layout を BiblioFetch.jl とどこまで互換に保つか。

Background

BiblioFetch.jl の現状: ~/papers/<safekey>.pdf + ~/papers/.metadata/<safekey>.toml (TOML 平文)。

Options

A. 完全互換

同じ safekey、同じ TOML schema。双方が同時に同じ store を読み書き可能。

B. 互換だが拡張

BiblioFetch.jl が読む field は維持、doiget 独自 field を追加 (mcp_call_id, agent_session_id, etc)。

C. 別 layout

doiget は独自 layout (例: ~/.local/share/doiget/)、BiblioFetch.jl と完全分離。

Recommendation

A から始めて必要に応じて B に拡張。共存モデルの key value、既存ユーザが doiget を試して store を壊す心配なし。

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Tightly coupled with #1 (coexistence) — read together.

立場

Recommendation "A から始めて必要に応じて B に拡張" を支持しますが、 A → B 移行を 無計画で許すと coexistence が崩壊する。 A / B の境界を spec として lock し、 doiget が独自 field を追加する規律を確定させる必要があります。

A (完全互換) の operational definition

「完全互換」は曖昧な目標なので、 検証可能な定義に書き直す:

A の合格条件: ある DOI / arXiv id に対して、

• BiblioFetch.jl が write した TOML を、 doiget が read できる
• doiget が write した TOML を、 BiblioFetch.jl が read できる (doiget が独自 field を書いた場合、 BiblioFetch.jl は無視するだけで落ちない)
• 両者が読み取った metadata の 共通 field 集合 で意味が一致する (e.g. title, authors, year, doi)
• BiblioFetch.jl の bib 出力 と doiget の bib 出力が 同じ DOI に対して diff 0

これを CI 自動 test で守る (#1 review で提案した cross-tool round-trip test)。

B (互換 + 拡張) の規律

「doiget 独自 field を追加する」のは benign に聞こえるが、 規律なしだと:

1. BiblioFetch.jl 側が doiget field を 誤解 する (例: mcp_call_id を comment と勘違い)
2. 第三者 tool が store を read するときに、 どの field が canonical か判断できない
3. 将来 BiblioFetch.jl が同名 field を別意味で導入する collision risk

→ 以下の 拡張規律 を本 Discussion で lock すべき:

規律 1: namespace 分離

doiget 独自 field は すべて [doiget] table 配下 に置く。 top-level に doiget 独自 field を撒かない。

schema_version = "1.0"
title = "Example Paper"
authors = ["Alice", "Bob"]
doi = "10.1234/example"
year = 2026

[doiget]
fetched_at = "2026-05-05T08:30:12Z"
fetched_via = "unpaywall"
oa_license = "CC-BY-4.0"
mcp_call_id = "..."

これで BiblioFetch.jl は [doiget] table 全体を「読まない / 触らない」だけ。

規律 2: doiget の write は top-level 共通 field に対して append のみ、 既存 BiblioFetch.jl 出力を modify しない

doiget が paper を fetch した結果、 既に store に entry があった場合:

• top-level 共通 field (BiblioFetch.jl が書いた可能性のある field) は 書き換えない
• [doiget] table 内のみ更新
• 例外: schema_version の bump は両側合意の上でのみ

これが守られないと、 BiblioFetch.jl user が doiget を一度走らせると 既存 metadata が壊れる。

規律 3: schema_version semantics

• 1.x 系は backward compatible (新 field 追加 / optional 化のみ)
• 2.x 系は breaking change を許す。 旧 reader は強制 read-only モードで warn
• doiget も BiblioFetch.jl も、 自分が知っている schema_version より新しいものを見たら read-only に降格

これを docs/STORE.md の normative section に明記。 両 implementation で同じ reader を持つ。

規律 4: Reserved field name list

将来 collision を避けるため、 共通 reserved field 名を予め declare:

reserved_top_level = ["schema_version", "title", "authors", "year", "doi",
                      "arxiv_id", "abstract", "venue", "keywords", "type",
                      "publisher", "issn", "isbn", "url", "pdf_path"]
reserved_tables = ["[doiget]", "[bibliofetch]"]

両 tool は reserved 外の名前を勝手に top-level に書かない。

規律 5: TOML 出力 normalization

bib 出力 / csl 出力で「diff 0」を保つには、 TOML 自体の write order / formatting も統一する必要がある:

• field 順序: schema_version → BibTeX 標準 field (alphabetical) → [doiget] table 末尾
• string quoting: 単純 ASCII は "..."、 multi-line は """..."""
• 改行: \n (LF only、 CR 入れない)

→ 共通 normalize_toml(metadata) -> String の reference implementation を test fixture で公開。

Reviewer Decision proposal

Decision: A から開始、 B への拡張は規律 1-5 に従う場合のみ許可。

• doiget 独自 field は [doiget] table 配下のみ (top-level append 禁止)
• top-level 共通 field の modify 禁止 (read 後 update は [doiget] 内のみ)
• schema_version semantics を 1.x backward compat / 2.x breaking で運用
• reserved field name list を docs/STORE.md に明記
• TOML normalization を 共通 reference implementation で確定

これを Phase 0 から CI guard:

• TOML output が normalization spec に従う (regression test)
• BiblioFetch.jl ↔ doiget round-trip integration test

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.