[design] BiblioFetch.jl との共存モデル

[sotashimozono]

Question

doiget が完成した後、Julia 版 BiblioFetch.jl との関係をどうするか。

Options

A. Side-by-side (parallel coexistence)

• BiblioFetch.jl は research / Julia REPL 用として継続
• doiget は agent / MCP / batch 用
• 同じ ~/papers/ store を共有 (TOML 互換)

B. doiget が eventual replacement

• 全機能を doiget に移し、BiblioFetch.jl は maintenance mode
• 単一プロダクトで責任所在明確

C. doiget は subset (e.g. PDF fetch のみ)、BiblioFetch.jl が full feature

• doiget は最小限の MCP wrapper
• 高度な機能は BiblioFetch.jl に集約

Recommendation

A (side-by-side)。理由：souta 自身は Julia REPL 中心の workflow / agent 市場と Julia 研究者市場は別 / store 共有で双方からアクセス可能なのが大きな価値。

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth).

立場

Recommendation A (side-by-side coexistence) を 支持 しますが、 "coexistence" を成立させる boundary contract が現状の Discussion 群で specify されていません。 #2 (store compat) と本 Discussion を組み合わせて、 lock すべき contract を以下に明示します。

Coexistence の boundary contract

side-by-side が成立する条件は、 双方が 同じ on-disk store を crash-safe / lock-safe / schema-evolve-safe に共有できる こと。これを 4 つの contract で表現:

Contract 1: Schema versioning (TOML metadata)

各 TOML metadata に必須 field として schema_version = "1.0" を持たせる。

• BiblioFetch.jl が future schema を見たとき は warn + read-only mode に降格
• doiget も同様
• schema bump (1.0 → 1.1) は backward-compatible 追加のみ。 breaking change は major bump (2.0) で、 旧 reader は強制 read-only

これを #2 で確定すべきこと。 本 Discussion では「schema versioning が coexistence の前提」と明記。

Contract 2: Concurrent access lock protocol

#12 (security) でも触れられている flock pattern を 両側で 同じ仕様 で実装する必要がある:

• Lock target: ~/papers/.metadata/<safekey>.toml.lock (separate file、 .toml 自体に lock しない)
• Lock acquire 失敗時 timeout: 5 秒
• 両側が 同じ lock file path を使う合意が必要 (片側が .lock 別側が .lck だと無意味)
• Cross-platform: Windows での flock 相当は LockFileEx — Rust なら fs2 crate、 Julia なら手動実装が必要

→ docs/STORE.md に flock spec を BiblioFetch.jl と doiget の 共有 normative document として置き、 双方の implementation で参照する。

Contract 3: Atomic write

部分書き込み破損を避けるため、 metadata write は atomic でなければならない:

1. write to <safekey>.toml.tmp
2. fsync(<safekey>.toml.tmp)
3. rename(<safekey>.toml.tmp -> <safekey>.toml)  # POSIX atomic
4. fsync(parent dir)

Windows は POSIX rename atomic 保証がない (MoveFileEx with MOVEFILE_REPLACE_EXISTING 必要、 Rust の std::fs::rename は内部で行う)。

→ 両 implementation で同じ手順を spec として持つ。

Contract 4: safekey algorithm

BiblioFetch.jl 側で安定した safekey 生成 algorithm が確定していて (#12 で言及されている H2 issue がある)、 doiget はそれと bit-identical に実装する必要がある:

• DOI / arXiv id → safekey の deterministic mapping
• collision-safe (path traversal を防ぎつつ identifier 区別を保つ)
• Windows / Linux / macOS で同じ output

→ docs/SAFEKEY.md に algorithm 仕様 + reference test vectors を置く (例: 100 個の DOI / arXiv id とその safekey の対表)。 双方の test suite で同じ vectors を pass することを CI で保証。

Migration story の不在

「side-by-side」は ~/papers/ を共有する場合の話だが、以下が discussion で扱われていません:

1. 既存 BiblioFetch.jl user が doiget を試す ときに、 既存 store を doiget が読めるかの guarantee
2. doiget user が BiblioFetch.jl を試す ときに、 doiget extension field (doiget_*) で BiblioFetch.jl が落ちないこと
3. Vault 移行 (例: ~/papers/ → ~/research/papers/ への移動) で双方が同期できるか

→ 提案: docs/MIGRATION.md で 上記 3 シナリオの test plan を書く。 Phase 0 から integration test を仕込む (BiblioFetch.jl を test fixture として CI で動かし、 doiget の write を Julia 側で読めるか check)。

Cross-tool round-trip test

Coexistence の 唯一の客観的な合格条件 は:

1. Julia: bibliofetch fetch DOI X → store に entry 作成
2. doiget: doiget info X → 同 entry 読める、 metadata が match
3. doiget: doiget bib X → BibTeX 出力、 BiblioFetch.jl の bib 出力と diff 0
4. doiget: doiget fetch DOI Y → store に entry 追加
5. Julia: BiblioFetch info Y → 読める、 doiget extension field で落ちない

これを CI で 自動実行すべき。 Phase 0 の最小 test 集合に含める。

Reviewer Decision proposal

Decision: A (side-by-side) を確定。 但し以下を coexistence の不可分な前提として明記:

• [design] BiblioFetch.jl と TOML store の互換性レベル #2 で schema versioning の 互換 layer を確定
• docs/STORE.md で BiblioFetch.jl + doiget の 共有 normative document を出す (flock spec / atomic write spec / lock file path 共通化)
• docs/SAFEKEY.md で safekey algorithm + 100 test vectors を normative spec 化
• docs/MIGRATION.md で 3 migration シナリオの test plan
• Phase 0 から cross-tool round-trip test を CI で 走らせる (Julia + doiget 両方を CI runner に install)

最終 Decision 権は author に留保。

---

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