foundry-core/docs/research-api.md

Shared research API (in progress)

This work belongs to Thesisly 研迹 and uses Foundry Core rather than a separate application backend. The corpus is public; account sessions and future private collections remain project scoped.

Current implementation boundary

internal/research implements the HTTP contract and repository boundary. It is not registered by cmd/foundry yet and does not open any database connection. The existing SQLite implementation was withdrawn. Wait for the separate Paper Atlas PostgreSQL migration to finish, inspect the published schema and indexes, then implement the repository with a least-privilege read-only connection and register it in the existing server. Do not add FOUNDRY_RESEARCH_DATABASE.

Routes

• GET /projects/{project}/research/papers
• GET /projects/{project}/research/papers/{id}

Only configured Foundry projects are accepted. Reading the public corpus does not require a session; these routes do not expose private data or accept writes.

List parameters are q (200 Unicode characters, 20 words), searchIn (text or author), topic (an exact arXiv category), sort (recent or title), page (1–1000), and pageSize (1–50, default 8). Unknown, malformed or repeated parameters return 400. recent means descending stable paper ID, not publication date. Search terms must become bound query parameters, never raw SQL or user-supplied full-text syntax.

List responses contain items, total, topics, page, and pageSize. Each paper preserves original title/abstract, authors, source dates, topics and source links. Publication decisions need source evidence; absent decisions stay unknown. No invented repositories, metrics or generated research conclusions.

The repository must count and read each list in one read-only snapshot. The HTTP layer permits two in-flight queries with an eight-second context budget. Busy requests return 429 with Retry-After: 1; deadlines return 504; storage errors return a generic 503 without database details. Missing papers return 404.

Validation

go test -race -count=1 ./internal/research covers routing, query limits, Unicode, anonymous reads, rejected mutations, project lookup, errors, saturation and timeout slot release. Run compilation/tests only on the user-confirmed ECS runner. These transport tests do not prove a database connection, full-corpus query performance or production availability.