Docs · reference
Architecture — API & MCP
BigBounce paper-orchestration state lives in Convex. The bigbounce-mcp server exposes 11 tools any MCP-aware agent (Claude Code, Codex, Cursor) can call to read or mutate that state — no hand-editing the unsynced surfaces this project used to maintain. See DATA_MODEL_ARCHITECTURE.md for the full rebuild plan.
Convex schema
7 paper-orchestration tables in convex/schema.ts, alongside the existing 9 object-level tables for galaxies, MCMC, and related science state:
| Table | Purpose |
|---|---|
| papers | Canonical per-paper state (NOT readiness — that's computed). |
| paper_versions | Append-only .tex version history. |
| r_rounds | Cross-vendor peer-review rounds. |
| findings | Individual R-round findings with a truth-audit lifecycle. |
| pathc_caveats | Paper-internal §pathc_caveats deferrals. |
| pods | RunPod lifecycle + cost accounting. |
| tasks | Open work queue (cross-paper + infrastructure). |
The load-bearing query is papers.getPaperState(slug) — it computes readiness as ceiling − 2·openBlockers − 1·openMajors − 0.2·openMinors − 1·openCaveats. The ceiling is the evidence-backed readinessCap. Current retained records: P1A 95, P1B 95, P2 95, P3 95, P4 95, P5 95 (average 84%). These are not equal submission targets — see /research for the current three-track framing. Automated-model verdicts and final-hash audits are evidence, not journal acceptance or a substitute for role-aware author decisions and venue-specific checks.
MCP tool catalog
Wire into Claude Code via bigbounce/.claude/mcp_servers.json with a CONVEX_URL env var. See mcp/bigbounce-mcp/README.md for install/build steps.
| Tool | Summary | Input | Returns |
|---|---|---|---|
| bigbounce_list_papers | Cross-paper dashboard with computed-readiness state. Read-only. The canonical 'where are we?' query. | (none) | Array<{ slug, number, shortTitle, status, currentVersion, lastUpdated, readinessComputed, openBlockers, openMajors, openMinors, openCaveats, houstonSignOff }> |
| bigbounce_get_paper | Full state for one paper by slug. Includes version history + R-round count + caveat counts + computed readiness. | { slug: string } | Paper state object (full) |
| bigbounce_list_open_findings | R-round work queue. Open findings (closureStatus = open | in-progress), optionally filtered by paper. | { paperSlug?: string } | Array<Finding> |
| bigbounce_truth_audit_finding | Apply truth-audit verdict to a finding (required before close, per the review truth-audit protocol). | { findingId: string, verdict: VERIFIED|FALSIFIED|STALE|OUT-OF-SCOPE|OPINION, evidence: string } | void (mutation) |
| bigbounce_close_finding | Atomic finding closure. Enforces the closureStatus enum + truth-audit-first ordering. | { findingId: string, closureStatus: enum, closureCommit?: string, closureArtifact?: string, closureNote?: string } | void (mutation) |
| bigbounce_bump_paper_version | Atomic .tex version bump. Site re-renders on Convex subscription — eliminates a 5-file hand-edit. | { paperSlug, version, datestamp, texCommit, pdfMd5, pdfPages, pdfSizeBytes, changelog, arxivTarballPath?, arxivTarballSizeBytes? } | Id<paper_versions> |
| bigbounce_list_pathc_caveats | Per-paper §pathc_caveats deferral list. Each item has a closureMethod enum. | { paperSlug: string } | Array<PathcCaveat> |
| bigbounce_close_pathc_caveat | Close a §pathc_caveats item. closureMethod enum includes an explicit text-only-no-real-action flag. | { paperSlug, label, closureMethod: enum, closureArtifact?, closureCommit?, closureNote? } | void (mutation) |
| bigbounce_list_pods | RunPod state synced from Convex. Includes cost accounting + backup-location tracking. | { statusFilter?: 'running'|'exited'|'terminated' } | Array<Pod> |
| bigbounce_get_external_review_prompt | Dynamic copy/paste external-review prompt for a paper's live PDF. | { slug: string } | { paperSlug, paperVersion, pdfPath, prompt } |
| bigbounce_list_tasks | Cross-paper + per-paper open task queue. | { status?, owner?, paperSlug? } | Array<Task> |
Skill package
5 Convex-backed slash commands at bigbounce/.claude/skills/, auto-loaded by Claude Code per-project:
/bigbounce-status — dashboard
/bigbounce-r-round <paper-slug> — fire direct-vendor R-round, write findings to Convex
/bigbounce-truth-audit <findingId> <verdict> <evidence> — required before close
/bigbounce-close — atomic finding/caveat closure
/bigbounce-bump <paper-slug> <version> — atomic version bump, site re-renders
Anti-pattern guards
Lessons learned, encoded in the MCP layer so no future round can regress:
No caveat-as-closure. closeFinding + closePathcCaveat require an explicit closureMethod enum. The value text-only-no-real-action is permitted but raises a flag (“simply disclosing deferred items and caveats is not real science”).
Truth-audit before close. Findings must have truthAuditVerdict set before close succeeds, per the review truth-audit protocol.
Provider routes are explicit and auditable. OpenAI-family review uses subscription-backed Codex/ChatGPT CLI sessions, never the OpenAI API. Direct Gemini and Grok API legs retain sanitized raw receipts. Anthropic is not part of the active review route. Provider failures remain failures rather than being silently replaced or relabeled.
No hand-set readiness. readinessComputed is derived from open findings + caveats. It cannot be patched directly via mutation.