From 9dd166d5de6b44f88f834fe392257cb6b1fd9389 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Sat, 7 Nov 2026 16:13:36 +0800 Subject: [PATCH] Finalize research API validation and handoff notes [skip ci] --- docs/research-api.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/research-api.md b/docs/research-api.md index bc825bb..08217ed 100644 --- a/docs/research-api.md +++ b/docs/research-api.md @@ -1,4 +1,4 @@ -# Shared research API (in progress) +# Shared research API This work belongs to Thesisly 研迹 and uses Foundry Core rather than a separate application backend. The corpus is public; account sessions and future private @@ -13,8 +13,11 @@ English title/abstract search index). `cmd/foundry` enables it only when count/content-hash acceptance. A dedicated `foundry_research_reader` role has SELECT on the ten tables consumed here, schema USAGE, and read-only defaults. Its connection is stored only in the protected server file below. -The existing SQLite implementation was withdrawn. Full-corpus API performance -and frontend integration still require verification before enabling production. +The existing SQLite implementation was withdrawn. Real-corpus integration has +been checked through a loopback Core and the local frontend. Formal production +release still requires the user to merge and choose to deploy; this branch is +not deployed by these checks. Very broad queries remain subject to the budget +and performance limitation documented below. Do not add `FOUNDRY_RESEARCH_DATABASE`. The server-side deployment may load a protected @@ -56,7 +59,7 @@ confirmed sequential scans for authors and category joins. `deploy/research/query-indexes.sql` supplies operator-run concurrent indexes for those two missing access paths. It is separate from Core startup and auth migrations; do not grant DDL to the runtime reader. Both indexes completed on the confirmed ECS (category 35.4 seconds, author -436.47 seconds); end-to-end timings are still under verification. +436.47 seconds); measured end-to-end checks are documented below. List responses contain `items`, `total`, `topics`, `page`, and `pageSize`. Each paper preserves original title/abstract, authors, source dates, topics and @@ -87,8 +90,8 @@ given name, family name and suffix; an optional fourth affiliation field is excluded from the display name (observed in real arXiv records); null abstracts/dates remain null. Publication status comes from the latest observed decision, using decision date and ID as tie-breakers, and stays unknown when no decision exists. Unit checks cover -author shapes, bound user values and schema qualification; real PostgreSQL -the real Core detail and homepage HTTP routes have returned 200. +author shapes, bound user values and schema qualification. The real Core detail +and homepage HTTP routes have returned 200. The frontend has also rendered the actual 3,526,999-paper corpus through a loopback SSH tunnel: eight rows, matching detail title/source, desktop and mobile layout, no page exceptions or horizontal overflow in that check. @@ -96,7 +99,9 @@ Author search returned 146 records in 0.336 seconds. After paging/author fixes, seconds, `CartoonGAN` returned three in 0.332 seconds, and the multi-term search `attention is all you need` returned 8,653 in 6.325 seconds. These were sequential manual HTTP checks, not a load test. Very broad text searches can still exceed -the eight-second budget and need further performance work. This is not a +the eight-second budget; clients retain search controls so users can narrow +the query or retry. This known limit is not an estimated count or sample +fallback. This is not a production deployment or an authentication acceptance result. The existing `deploy/check-schema.sh` also loads the synthetic fixture in @@ -119,9 +124,22 @@ unsupported marked codec or malformed encoded text fails explicitly. Schema comments are public metadata, so consumers need no privileges on the private migration controller. The research role still needs only schema USAGE -and table SELECT. The codec adaptation remains local without CI or branch pushes; -the published schema marker has been verified with the runtime reader. +and table SELECT. The codec adaptation is on the review branch, pushed with [skip ci] under the +user's no-CI instruction; the published schema marker has been verified with +the runtime reader. All research tests passed manually against disposable PostgreSQL on the confirmed ECS, including the encoded SQL fixture for schema detection, raw TEXT restoration, JSON author/metadata decoding, search and the HTTP round trip. Passing isolated fixtures does not establish full-corpus API performance. + + +## Identity handoff + +The existing production Core received a configuration-only reload using its +unchanged release binary: the original projects were retained and thesisly was +registered. Both Google and Slack identity records were observed in this +project. The user independently confirmed each provider's real authorization, +reload/new-tab persistence and logout behavior. Browser control was unavailable, +so these browser results are attributed to user acceptance rather than an +automated real-account test. This does not deploy the research work branch; +mail delivery was not exercised.