refactor(paper): add source-first Paper Flow V1

[keli-wen]

Summary

• Replaces the model-authored Paper(TreeKnowledge) output with a source-first PaperFlowResult containing an immutable exact source revision, a deterministic page-aware PaperChunkSet, and an independently versioned cited PaperGlobalSummary.
• Implements manager-style multi-agent summarization with the OpenAI Agents SDK: one coordinator retains final-summary ownership, delegates required chunk ranges through a real Agent.as_tool() research specialist, permits bounded parallel and overlapping follow-up calls, and rejects incomplete source coverage.
• Enforces shared research call, concurrency, turn, input-token, worker-output, total-output, final-output, citation, and runtime limits. Worker reports contain typed context/contribution/method/result/limitation findings with code-validated chunk/page coordinates.
• Replaces the open list[str] paper search filter with the Pydantic-validated PaperArtifactKind enum. Python callers use PaperArtifactKind.GLOBAL_SUMMARY or PaperArtifactKind.CHUNK_SET; JSON and YAML retain the corresponding string values while unknown kinds fail validation.
• Adds SQLite schema version 3 with explicit source/blob, artifact/member, lineage, and search-projection tables; atomic put_paper(); selective embedding reuse; reopen-safe locator resolution; cross-record integrity checks; and a tested LegacyPaper compatibility boundary for existing databases.
• Moves retrieval-text selection out of canonical knowledge models, preserves existing non-paper search behavior, and documents the Source → Artifact → SearchProjection contract across flow, knowledge, RAG, library, examples, and contributor guidance.

The cross-flow placement and reuse policy for Pydantic input/config types is intentionally tracked separately in #121 instead of being decided implicitly by this paper refactor.

Related Issues

Closes #119

• design(config): define ownership of typed operation inputs #121 tracks ownership, reuse, naming, supported-variant, schema, and migration rules for typed operation inputs and stage configuration.

Breaking Changes

• paper_flow() now returns PaperFlowResult and supports PDF-backed arXiv, HTTP, and local inputs in V1; raw text, non-PDF content, and unresolved DOI inputs fail explicitly.
• The former primary Paper tree is no longer exported or generated. Existing version-2 databases and the bundled compatibility example load that shape as LegacyPaper.
• SemanticQuery.artifact_kinds now validates as list[PaperArtifactKind]; valid serialized string values remain paper_summary and paper_chunk_set.

Verification

• ./scripts/verify.sh — PASS: ruff format/check, basedpyright with 0 errors and warnings, all 7 import contracts, 335 tests, and 83.69% coverage.
• .venv/bin/python scripts/verify_pdf_rag_e2e.py — live PASS against exact arXiv revision 1706.03762v7: manager/research-agent orchestration, complete coverage of 36 chunks, 15 text pages, 19 source assets, 42 chunk-to-asset references, cited summary across 7 pages, summary retrieval, multi-head-attention passages in the top five, close/reopen, repeated searches, and canonical locator resolution.
• Focused config, flow, library, and live-verifier tests — PASS: 41 tests cover typed artifact parsing, real agent-tool construction, worker concurrency and budgets, complete-coverage enforcement, persistence, retrieval, and E2E assertions.
• Commit and pre-push hooks — PASS: file hygiene, YAML validation, large-file check, ruff, and the deterministic verification harness.
• GitHub Actions — required ci PASS; the paper-flow job PASS with its live step explicitly skipped because the repository has no OPENAI_API_KEY; the unrelated news job failed on both the initial run and one retry because PR Newswire returned 404 for its RSS endpoint while the discovery and ticker-hint checks passed.

Checklist

• The title uses English Conventional Commit format: type(scope): summary.
• The related issue or design discussion is linked when applicable.
• ./scripts/verify.sh passes.
• Every applicable live-network component smoke test passes, or this PR states why none applies.
• Public behavior has focused tests, an example, and documentation where applicable.
• The PR contains no unrelated changes.