Add bounded public research HTTP contract and transport tests

2026-11-07 01:58:30 +08:00
parent 2207c85ca6
commit 81cf7d9448
3 changed files with 394 additions and 0 deletions
@@ -0,0 +1,47 @@
+# 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.