# 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.