From 3b9f977bf74cf102b2f4b419e59e2a75dc6ed313 Mon Sep 17 00:00:00 2001 From: odieyang <520yangziqi@gmail.com> Date: Sun, 2 Aug 2026 18:57:39 -0700 Subject: [PATCH 1/2] docs(deploy): add the deployment plan and point CLAUDE.md at it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Deploy.md is the authority for taking this online. It records the three decisions taken (real models via hosted APIs, a login gate between landing and workbench, Railway), the platform constraints that were verified rather than assumed, the invariants this workstream may not break, five PRs with binding acceptance criteria, and a findings register. Two things about the register are deliberate. Every row carries a file:line so it can be checked instead of believed, and each row is marked `direct` (confirmed in-session by reading the file or resolving the compose config) or `audit` (reported with a citation by a code-audit pass, not independently re-checked). Treating those two as the same kind of claim is how a plan acquires facts nobody verified. The register is not a second backlog. Final_Report.md keeps the single outstanding-work list for the product; Deploy.md covers only what blocks deployment, and where an item is both it gets struck from Outstanding Work in the PR that fixes it. The constraint that outranks the rest is model parity: every figure the UI and the docs display is generated from results/eval-h1-repeat3-2026-07-31/ and is a claim about that exact configuration. All three of its models are available as hosted APIs, so the deployment can match it without substituting anything — and if a future change substitutes one, it says so on the landing page and /methodology or it reverts. CLAUDE.md gets a pointer, not a copy: §2 carries only the seven invariants that stay true whichever PR is in flight, and says explicitly that the backlog lives in Deploy.md. Three copies of "what's left" is the drift pattern this project keeps having to fix. Sections renumbered 2-6 -> 3-7; the two internal §1 references still resolve. --- CLAUDE.md | 60 ++++++- Deploy.md | 507 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 561 insertions(+), 6 deletions(-) create mode 100644 Deploy.md diff --git a/CLAUDE.md b/CLAUDE.md index 6ab0c39..f37f45a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,11 +7,12 @@ rules, and how to not break things. **Read this, then `git log --oneline`.** The work is committed in small scoped slices and the messages carry the reasoning. -Project documentation is five files, all authoritative over this one: +Project documentation is six files, all authoritative over this one: | Document | Read it for | |---|---| | [`docs/en/Final_Report.md`](docs/en/Final_Report.md) | The H1 verdict, **the single outstanding-work list**, known limits, what was verified | +| [`Deploy.md`](Deploy.md) | **Everything about taking this online.** Decisions, verified platform constraints, the invariants, the PR breakdown, the findings register — see §2 below | | [`docs/en/Honesty_Constraints.md`](docs/en/Honesty_Constraints.md) | The eleven rules governing what the UI may assert, with reasoning. Most are pinned by tests — read before touching the thread, the chips, or the inspector | | [`docs/en/Technical_Design.md`](docs/en/Technical_Design.md) | Repository layout, architecture, data model, API contracts | | [`docs/en/Operations.md`](docs/en/Operations.md) | Running the stack, the real-model path, the eval harness, operational gotchas | @@ -56,7 +57,54 @@ its numbers are generated rather than translated. flows, and write drafts to files rather than printing them inline. Pure frontend work runs clean. -## 2. Where things are +## 2. Deployment work is governed by `Deploy.md` — follow it strictly + +If the task touches deployment, hosting, model providers, auth, or production +configuration, **read [`Deploy.md`](Deploy.md) first and execute against it.** It +carries the decisions, the verified Railway constraints, the five-PR breakdown +with binding acceptance criteria, and a findings register where every row has a +`file:line`. Do not re-derive that plan, and do not improvise around it. + +**The backlog is not copied here.** `Deploy.md` §6 and §7 are the single list; +duplicating them into this file is the exact drift pattern this project keeps +having to fix. What is repeated below is only the set of invariants — the things +that stay true no matter which PR is in flight. + +1. **The deployed models must be the evaluated models.** + `jinaai/jina-embeddings-v2-base-code` at 768 dimensions, `BAAI/bge-reranker-v2-m3`, + `gpt-4o-mini`. Every figure the UI and the docs display is generated from + `results/eval-h1-repeat3-2026-07-31/` and is a claim about *that* configuration. + Substituting a model without saying so on the landing page and `/methodology` + is the same class of error as hand-typing a figure into prose. `Deploy.md` §2. +2. **The local multi-container path must not regress.** All four modes keep + working: stub, Docker sidecars, host sidecars, and the new API-provider mode. + `apps/embedding/`, `apps/reranker/`, the Compose profiles, the host scripts, + `HttpEmbeddingClient` and `HttpRerankerClient` are untouched. In particular the + agent+worker merge is a **Railway-only entrypoint** — Railway cannot share a + volume between services and local Docker can, so `docker-compose.yml` keeps two + separate containers. Do not degrade the local path to match the constrained + one. `Deploy.md` §5.1. +3. **The provider switch is additive.** `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` + default to `sidecar`; existing `.env` files and tests keep their behaviour with + no edit. `Deploy.md` §5.2. +4. **CI stays keyless.** New client tests mock the transport; they never call a + live API. `Deploy.md` §5.3. +5. **Embedding configuration must match on the API and the worker.** Setting it on + one only produces no error — it produces real vectors in the database searched + with a stub all-zero query vector, i.e. dense retrieval silently returning + noise. `Deploy.md` §5.4. +6. **No fork, no long-lived divergent branch.** `Deploy` merges to `main` as small + PRs, each independently green under `make check`. Secrets never enter the + repository. `Deploy.md` §5.5. +7. **`docker-compose.prod.yml` is fixed, not deleted.** `Final_Report.md` lists it + as delivered. `Deploy.md` §5.6. + +The pre-deployment state is frozen at tag `v1.0-submission` (`a4612b8`). Two +Railway constraints are load-bearing and were verified on 2026-08-02: a volume +attaches to exactly one service, and an HTTP request is cut after 5 minutes with +no data (~15 minutes with heartbeats). + +## 3. Where things are ``` apps/frontend/ React 18 + TS strict + Vite + Tailwind + Router v6 + TanStack Query (~4.2k TS/TSX lines) @@ -101,7 +149,7 @@ which matches `dcode_shared.events.sse_encode` emitting pure LF. Two data-fetching paradigms coexist deliberately: TanStack Query for status polling, hand-rolled streaming for the query. That is not an inconsistency. -## 3. Visual identity — deliberate, do not "improve" +## 4. Visual identity — deliberate, do not "improve" Tokens are a CSS-vars layer in `apps/frontend/src/index.css`, with `tailwind.config.ts` pointing at the vars so `color-mix` translucency still works. @@ -134,7 +182,7 @@ let it fill the `1fr` column: serif prose at 100+ characters per line is unreadable, and on a wide monitor a full-bleed column reads as an empty void. The rails (262px left, 384px right) are correct as-is. -## 4. Current state +## 5. Current state Everything below is committed and green: `make check`, `make frontend-build`, 71 frontend tests, full pytest suite. @@ -199,7 +247,7 @@ duplicate `psf/requests` rows already in the local DB are not cleaned up retroactively by the `POST /repos` idempotency fix, and `make down-all` wipes the volumes, which means re-indexing at whatever `EMBEDDING_DIM` you migrate at. -## 5. Environment +## 6. Environment ```bash # All three are required — .env points the model endpoints at host.docker.internal, @@ -242,7 +290,7 @@ vectors — real, varied embeddings, not stubs. Inspector line numbers and call-graph neighbours were manually verified against this index and matched exactly. -## 6. Working agreements that produced good results +## 7. Working agreements that produced good results - **Where this file and the code disagree, the code is the truth.** These notes are written from the approved intent of a session, and intent occasionally diff --git a/Deploy.md b/Deploy.md new file mode 100644 index 0000000..997b716 --- /dev/null +++ b/Deploy.md @@ -0,0 +1,507 @@ +# Dcode Deployment Plan + +## Document Scope + +This document is the authority for taking Dcode online. It records the decisions +that were taken, the platform constraints that were verified, the invariants this +workstream may not break, and the work broken into reviewable slices. + +It is deliberately **not** a second copy of the project backlog. +[`docs/en/Final_Report.md` § Outstanding Work](docs/en/Final_Report.md#outstanding-work) +remains the single list of what is unfinished in the *product*; this file covers +only what is unfinished in *getting it deployed*. When a deployment item is also +a product defect — most of them are — it is fixed here and struck from the +Outstanding Work list in the same PR, not tracked in two places. + +| Read instead | For | +|---|---| +| [`docs/en/Final_Report.md`](docs/en/Final_Report.md) | The H1 verdict and the product backlog | +| [`docs/en/Technical_Design.md`](docs/en/Technical_Design.md) | Architecture, data model, API contracts | +| [`docs/en/Operations.md`](docs/en/Operations.md) | Running the stack locally, the real-model path, the eval harness | +| [`docs/en/Honesty_Constraints.md`](docs/en/Honesty_Constraints.md) | What the UI may assert | +| [`CLAUDE.md`](CLAUDE.md) | Session-level operational notes; §2 there points back here | + +**Where this document and the code disagree, the code is the truth.** This file +is written from an approved plan, and plans outrun implementations. Verify before +relying on a claim here, and correct it when it is wrong. + +**Status: planning. Nothing in § 6 has been implemented.** The pre-deployment +state is frozen at tag `v1.0-submission` (`a4612b8`). + +--- + +## 1. Decisions Taken + +Recorded so a later reader can see what was chosen and what it ruled out. + +| # | Decision | Date | Consequence | +|---|---|---|---| +| D-1 | **Run real models, served by third-party APIs**, not self-hosted sidecars | 2026-08-02 | No GPU/RAM budget for model serving; adds API keys, network dependency, and per-query cost. Makes § 2 possible. | +| D-2 | **Not publicly accessible.** A username/password gate sits between the landing page and the workbench | 2026-08-02 | Removes the anonymous-abuse surface (F-01, F-03 below) as a launch blocker. Landing and `/methodology` stay public; the product does not. | +| D-3 | **Deploy to Railway** | 2026-08-02 | TLS, certificates and a public hostname are solved by the platform. Two platform constraints in § 3 change the topology. | +| D-4 | **No fork. `Deploy` is a normal feature branch, merged back to `main` in slices** | 2026-08-02 | See § 5.5. | + +Decisions still open are in § 11. + +--- + +## 2. Model Configuration Parity + +**This constraint outranks every other item in this document.** + +The project's central property is that the figures on `/methodology`, in +`README.md` and in `Final_Report.md` describe the system that is actually +running. All of them are generated from +`results/eval-h1-repeat3-2026-07-31/` by `scripts/sync_eval_artifacts.py`, and +`make check` fails if any displayed surface drifts from that directory. + +That recorded run used exactly three models: + +| Role | Model | Dimension | +|---|---|---| +| Embedding | `jinaai/jina-embeddings-v2-base-code` | 768 | +| Reranker | `BAAI/bge-reranker-v2-m3` | — | +| Synthesis | `gpt-4o-mini` | — | + +All three are available as hosted APIs, so **D-1 can be satisfied without +changing a single model**: + +| Role | Provider | Endpoint | Model id | +|---|---|---|---| +| Embedding | Jina AI | `https://api.jina.ai/v1/embeddings` | `jina-embeddings-v2-base-code` | +| Reranker | SiliconFlow | `https://api.siliconflow.cn/v1/rerank` | `BAAI/bge-reranker-v2-m3` | +| Synthesis | OpenAI | `https://api.openai.com/v1` (already supported via `OPENAI_BASE_URL`) | `gpt-4o-mini` | + +**The rule.** The deployed configuration must use these three models. If a future +change substitutes any of them — a different embedding model, Jina's own +reranker instead of BGE, a different synthesis model — then the generated figures +no longer describe the deployed system, and one of two things must happen in the +same change: + +1. the substitution is reverted; or +2. the landing page and `/methodology` carry an explicit statement that the + deployed configuration differs from the evaluated one, naming the difference. + +Silently deploying different models under the same numbers is the single most +damaging thing this workstream could do. It is not a performance question; it is +the same class of error as hand-typing a figure into prose. + +**A caveat that is not resolved.** Serving the same weights through a provider's +API is not bit-identical to serving them locally: batching, quantization, and +model-version pinning are the provider's decisions, not ours. Parity of *model +identity* is achievable and required; parity of *output* is not guaranteed. This +does not affect the recorded verdict, which stays the authority and is not +regenerated. It does mean that **if the H1 suite is ever re-run through the API +providers, that is a new run directory with its own `provenance.json`, not a +refresh of the recorded snapshot.** + +### 2.1 Not yet verified + +Two facts this plan depends on and that must be confirmed with a live call +**before** the database volume is migrated, because `chunks.embedding` fixes its +dimension at migration time: + +- **Jina's API returns 768-dimensional vectors for `jina-embeddings-v2-base-code`.** + The model card and the recorded run both say 768, but the API response was not + observed in this session. One request settles it. +- **SiliconFlow's rerank request/response field names.** The client in § 6.2 must + be written against the observed payload, not against an assumed one. + +--- + +## 3. Verified Platform Constraints (Railway) + +Checked against Railway's documentation and community answers on **2026-08-02**. +Platform behaviour changes; re-verify before relying on any row. + +| # | Constraint | Consequence for Dcode | +|---|---|---| +| R-1 | **A volume can be attached to only one service.** Railway recommends sharing data through Postgres/Redis rather than a volume. | `repo_workdirs` is written by `worker` and read by `agent` (`docker-compose.yml:103-104`, `:185-186`). The agent's `read_file` / `grep` / `list_directory` tools read that tree directly and raise `FileNotFoundError` without it (`apps/agent/src/dcode_agent/tools/common.py:38-43`). **Worker and agent must therefore share one Railway service.** | +| R-2 | **HTTP requests are closed after 5 minutes with no data transferred, and capped at ~15 minutes with keep-alive heartbeats.** | The agent emits no heartbeat frames and has **no overall request timeout** at all — `/internal/query` spawns a task and returns a stream immediately (`apps/agent/src/dcode_agent/main.py:94-109`), with per-hop timeouts only, giving a theoretical upper bound past 8 minutes. Needs both a heartbeat and a hard budget. | +| R-3 | **The default Postgres template does not ship pgvector**; the extension must exist at the server level. | Use a pgvector template for the Postgres service. `infra/postgres/init.sql` only runs `CREATE EXTENSION IF NOT EXISTS vector`, which fails if the binary is absent. | +| R-4 | **Private-network DNS names (`*.railway.internal`) change IP on every redeploy**, and legacy environments resolve IPv6-only. | nginx caches DNS resolution indefinitely with a literal `proxy_pass`. The frontend config must use `resolver [fd12::10] ipv6=on valid=1s;` plus a variable-form `proxy_pass`. | + +R-1 is the only one that changes the architecture. R-2 through R-4 are configuration. + +--- + +## 4. Target Topology + +``` + [ public HTTPS — Railway-managed TLS ] + │ + ┌────────────▼────────────┐ + │ frontend │ public + │ nginx + static bundle │ + └────────────┬────────────┘ + │ /api/* → api.railway.internal:8000 + ┌────────────▼────────────┐ + │ api │ private + │ FastAPI gateway + auth │ + └────────────┬────────────┘ + │ AGENT_URL → agent-worker.railway.internal:8001 + ┌────────────▼────────────┐ + │ agent-worker │ private, owns the only volume + │ agent (:8001) + worker │ + └────────────┬────────────┘ + │ + ┌──────────────────────────────┼──────────────────────────────┐ + ▼ ▼ ▼ + Postgres (pgvector) Redis RabbitMQ +``` + +Six services. The public surface is unchanged from the documented design: the +frontend is the only thing reachable, and it proxies `/api/*` to an API that is +still the only backend entry point. Merging `agent` and `worker` into one +container is a **platform workaround for R-1**, not an architectural revision — +the agent still exposes only `/internal/*` behind the internal API key, and the +worker still consumes from RabbitMQ. + +--- + +## 5. Standing Constraints for This Workstream + +These are invariants. A PR that breaks one should not merge, even if it works. + +### 5.1 The local multi-container path must not regress + +Every mode that works today must still work after this workstream: + +| Mode | How it starts | Needs network / keys | +|---|---|---| +| stub | `make up` | no | +| Docker sidecars | `make up-embed` / `make up-rerank` | weights download on first run | +| host sidecars | `make embedding-host` + `make reranker-host` + `make up` | weights download on first run | +| **API providers (new)** | `make up` with `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` set | yes | + +Concretely: `apps/embedding/`, `apps/reranker/`, the `embedding` / `reranker` +Compose profiles, `scripts/start-*-host.sh`, `HttpEmbeddingClient` and +`HttpRerankerClient` are all **untouched** by this workstream. + +The one place this could be broken carelessly is R-1. The worker+agent merge is a +Railway-only entrypoint. `dcode_agent.main:app` and `dcode_worker.main` both keep +their own entrypoints (`infra/docker/agent.Dockerfile:22-24`, +`infra/docker/worker.Dockerfile:21`), and `docker-compose.yml` keeps two separate +containers sharing the volume. **Local Docker supports shared volumes; Railway +does not. That is a platform difference, not a code difference, and the local +path must not be degraded to match the constrained one.** + +### 5.2 The provider switch is additive, not a replacement + +`create_embedding_client()` (`packages/shared/src/dcode_shared/embedding.py:125-149`) +and `create_reranker_client()` (`packages/shared/src/dcode_shared/reranker.py:109-127`) +currently branch on one condition, `model == "stub"`. The API providers are a new +branch beside the existing sidecar branch, selected by an explicit +`EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` whose default is `sidecar`. Existing +`.env` files, existing tests, and existing Compose invocations keep their current +behaviour with no edit. + +### 5.3 CI stays keyless + +`.github/workflows/ci.yml` currently requires no secrets. It must still require +none. Tests for the new clients mock the HTTP layer; they never call a live API. + +### 5.4 Embedding configuration must be identical on `api` and `agent-worker` + +The worker writes vectors at index time; the API embeds the query at search time. +They are separate processes reading the same settings. Setting the provider on +one and not the other produces **no error** — it produces Jina vectors in the +database being searched with a stub all-zero query vector +(`packages/shared/src/dcode_shared/embedding.py:37-38`), i.e. dense retrieval +silently returning noise. This is already latent in `docker-compose.prod.yml`, +where the `api` service has no embedding configuration at all (F-02). + +The mitigation is not discipline. It is the readiness check in PR 5: compare the +configured `EMBEDDING_DIM` against the live `vector_dims` of `chunks.embedding` +at startup and report not-ready on a mismatch, rather than discovering it on the +first insert. + +### 5.5 Branch and release policy + +- No fork. `Deploy` is a feature branch; the work merges to `main` as the five + PRs in § 6, each independently green under `make check`. +- Nothing lands on `main` that leaves it in a worse state than `v1.0-submission`. +- Secrets never enter the repository. `.gitignore:11-14` already covers `.env`, + `.env.production`, `.env.local`; Railway environment variables are configured + in the Railway dashboard, not in a committed file. +- `.env.production.example` stays committed and stays free of real values. + +### 5.6 `docker-compose.prod.yml` is fixed, not deleted + +`Final_Report.md` lists "a production-shaped Docker Compose package" as +delivered. Deleting it to make room for Railway would turn that into a false +claim. After this workstream there are two supported paths — self-hosted Compose +and hosted Railway — and the Compose path is where the Railway configuration gets +validated locally before it is pushed. + +### 5.7 Displayed numbers are still generated, never typed + +Unchanged from `CLAUDE.md`, restated because this workstream touches +configuration rather than results and the rule is easy to forget in that context: +no figure from `results/` may be hand-written into `Deploy.md`, the README, the +UI, or a Railway description. + +--- + +## 6. Work Breakdown + +Five PRs, in dependency order. Each is independently reviewable, independently +revertable, and must pass `make check` and `make frontend-build` on its own. + +**Acceptance criteria are binding.** A PR is not done when the code is written; +it is done when its criteria are demonstrated, and honestly reported when they +are not. + +### PR 1 — `fix/prod-compose-model-env` + +Pure defect repair. Smallest, lands first, useful even if deployment never +happens. + +| Item | Detail | +|---|---| +| F-02 | Add `EMBEDDING_MODEL`, `EMBEDDING_DIM`, `EMBEDDING_ENDPOINT`, `RERANKER_MODEL`, `RERANKER_ENDPOINT` and the retry/limit knobs to the `api` service in `docker-compose.prod.yml`. Today it has none (`:47-54`), so `make prod-migrate` builds a `vector` column at the code default of 1024 (`packages/shared/src/dcode_shared/settings.py:46`, read by `infra/migrations/versions/001_initial_schema.py:91`) regardless of `.env.production`, and the API's dense path silently runs on `stub`. | +| F-11 | Reconcile the two documented Compose invocations: `README.md:324` uses `-f docker-compose.prod.yml` alone; `.env.production.example:4-5` documents overlaying it on `docker-compose.yml`. The overlay form republishes Postgres, Redis and the RabbitMQ management UI to the host. Pick the standalone form and correct the other. | +| F-12 | Remove the dead `RERANKER_ENDPOINT=http://localhost:9999` default from `docker-compose.prod.yml:110` and `.env.production.example:37`. | +| F-13 | Reduce embedding retry aggression for the API path: `max_retries=12` against a 300 s timeout (`embedding.py:19-20`) can occupy a single batch of four chunks for roughly an hour, and the worker is `prefetch_count=1`, so the whole indexing queue stalls behind it. | + +**Acceptance.** `docker compose --env-file -f docker-compose.prod.yml config` +shows a complete and consistent embedding configuration on `api`, `worker` and +`agent`. `make check` green. + +### PR 2 — `feat/managed-model-providers` + +The capability behind D-1. + +- Add `JinaApiEmbeddingClient` to `packages/shared/src/dcode_shared/embedding.py`. + The sidecar contract is an unauthenticated `POST {endpoint}/embed` with + `{"texts": [...]}` returning `{"embeddings": [[...]]}` (`embedding.py:87-90`); + Jina's is an authenticated `POST /v1/embeddings` with `{"model", "input"}` + returning `{"data": [{"index", "embedding"}]}`. **Results must be reordered by + `index`, not trusted in arrival order.** +- Add the SiliconFlow reranker client to + `packages/shared/src/dcode_shared/reranker.py`. Same shape of problem: the + sidecar returns `{"scores": [...]}` in passage order (`reranker.py:54-61`); + a rerank API returns scored results carrying their own index, which must be + mapped back to input order before returning. +- Select with `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER`, default `sidecar` + (§ 5.2). Add `EMBEDDING_API_KEY` / `RERANKER_API_KEY`. +- Timeouts and retries appropriate to a hosted API, not to a cold local model. + +**Acceptance.** + +1. Unit tests with a mocked transport cover: correct reordering, dimension + validation, auth header present, non-retryable 4xx surfacing, retryable 5xx + retrying. No live calls (§ 5.3). +2. **A live local run, reported with real observed values:** index `psf/requests` + with `EMBEDDING_PROVIDER=jina_api`, then confirm from the database that the + vectors are 768-dimensional and non-zero — this is the § 2.1 check and it must + happen before any Railway volume is migrated. Confirm the reranker is + materially reordering results rather than passing through. +3. `make check` green, and all four modes in § 5.1 still start. + +### PR 3 — `feat/auth-gate` + +D-2. Also closes F-01 and F-03. + +- `POST /api/v1/auth/login`, `POST /api/v1/auth/logout`, `GET /api/v1/auth/me`. + Credentials from environment (password stored as a hash, never plaintext in the + repo or in a committed file). Signed, `HttpOnly`, `Secure`, `SameSite=Lax` + cookie. +- A dependency on the `repos`, `query` and `inspector` routers + (`apps/api/src/dcode_api/main.py:45-47`). `/healthz` stays open. +- Frontend `/login` route; `/workbench` checks the session and redirects on 401. + `/` and `/methodology` remain public — they are the part meant to be read. +- F-05: disable `/docs`, `/redoc` and `/openapi.json` in production. They are + public today and advertise the `/internal/*` surface. +- A per-session daily query cap. The login wall removes anonymous abuse; it does + not remove a logged-in user looping a query against a metered API. + +**Acceptance.** An unauthenticated request to each protected route returns 401. +`/`, `/methodology` and `/healthz` are reachable without a session. The +`/workbench` redirect is verified **by a human in a browser** — headless +screenshots do not work in this environment, and that limitation is not a reason +to claim the check passed. + +### PR 4 — `feat/railway-deploy` + +The only Railway-specific PR. Mostly additive files. + +- R-1: a combined `agent` + `worker` entrypoint used **only** by the Railway + service. `docker-compose.yml` is not touched (§ 5.1). +- R-2: SSE heartbeat frames (a `:` comment line on an interval below Railway's + 5-minute idle cut). The frontend parser already skips `:` lines + (`apps/frontend/src/api/client.ts:142-144`), so no frontend change is required. + Plus an overall agent request budget that expires inside Railway's window and + emits a clean `error` event rather than being cut by the platform. +- R-4 and static-serving fixes in `apps/frontend/nginx.conf`: variable-form + `proxy_pass` with `resolver`, an explicit `proxy_read_timeout` for the SSE + path, `listen` on the platform-assigned port, **gzip on** (verified off by + default in `nginx:1.27-alpine`; the built main chunk is 752.53 kB, 226.74 kB + gzipped), and long-lived cache headers on hashed assets. +- A root `.dockerignore` and one for `apps/frontend` (the frontend build context + currently ships 227 MB of `node_modules` to the daemon; the root context is + 391 MB). +- F-09: `GET /api/v1/repos` so the workbench can list indexed repositories. + Today the switcher reads `localStorage` only + (`apps/frontend/src/lib/recentRepos.ts:8`) and there is no default repository, + so a first-time visitor on a new device sees an empty workbench. + +**Acceptance.** A live deployment reachable over HTTPS; login works; one indexed +repository is selectable; a query streams to completion with verified citations; +clicking a citation opens real indexed source. Every one of those is confirmed by +a human in a browser and reported with what was actually seen. + +### PR 5 — `fix/audit-followups` + +Findings that are not launch blockers but should not ship unaddressed. +See the register in § 7 for F-04, F-06, F-07, F-08, F-10, F-14, F-15. + +**Acceptance.** Each item either fixed with a test, or explicitly deferred in +this document with a reason. Silence is not an outcome. + +--- + +## 7. Findings Register + +Every row carries a `file:line` so it can be checked rather than believed. + +**Verification column.** `direct` — confirmed in this session by reading the file, +running the command, or resolving the Compose config. `audit` — reported by a +code-audit pass with a citation, not independently re-checked. Treat `audit` rows +as leads to verify when the PR touches them, not as established fact. + +| # | Finding | Where | Severity | PR | Verified | +|---|---|---|---|---|---| +| F-01 | No authentication of any kind on `/api/v1/*`; no user or tenant concept, so any caller can read any indexed repo by `repo_id` | `apps/api/src/dcode_api/main.py:45-47` | blocker | 3 | audit | +| F-02 | The `api` service in the production Compose file has no embedding or reranker configuration | `docker-compose.prod.yml:47-54` | blocker | 1 | **direct** | +| F-03 | No rate limiting, no request-size limit, no quota. `QueryRequest.query` has `min_length` but no `max_length` | `packages/shared/src/dcode_shared/schemas.py:132` | blocker | 3 | audit | +| F-04 | `INTERNAL_API_KEY` defaults to a literal published in this repository, with no startup guard outside Compose's `:?` operator — and Railway sets variables per service, so that operator does not protect the deployment | `packages/shared/src/dcode_shared/settings.py:33` | high | 5 | audit | +| F-05 | `/docs`, `/redoc` and `/openapi.json` are publicly served and advertise the `/internal/*` surface | `apps/api/src/dcode_api/main.py:31-35` | high | 3 | audit | +| F-06 | SSRF: repository URL validation rejects literal private IPs but has no host allowlist and no resolution check, so a hostname resolving to an internal address passes | `apps/api/src/dcode_api/routes/repos.py:203-224` | high | 5 | audit | +| F-07 | The agent tool cache key omits `index_revision`, so re-indexing a repository does not invalidate cached tool results for up to 24 h | `apps/agent/src/dcode_agent/graph.py:119` | high | 5 | audit | +| F-08 | Cloned workdirs are never cleaned up, for any repository, ever. On a fixed Railway volume this is unbounded growth | `apps/worker/src/dcode_worker/stages/clone.py:17-22` | high | 5 | audit | +| F-09 | No repository list endpoint; the switcher reads `localStorage` only and there is no default repository | `apps/frontend/src/lib/recentRepos.ts:8` | high | 4 | **direct** | +| F-10 | `/healthz` returns `ok` unconditionally — it reports healthy with every dependency down. No readiness probe exists | `apps/api/src/dcode_api/main.py:51-54` | medium | 5 | audit | +| F-11 | The two documented production Compose invocations disagree; one of them republishes Postgres, Redis and the RabbitMQ UI | `README.md:324` vs `.env.production.example:4-5` | medium | 1 | **direct** | +| F-12 | `RERANKER_ENDPOINT` defaults to a dead loopback address in the production template | `docker-compose.prod.yml:110`, `.env.production.example:37` | medium | 1 | **direct** | +| F-13 | Embedding retries are 12 attempts against a 300 s timeout; with `prefetch_count=1` one bad batch stalls the entire indexing queue | `packages/shared/src/dcode_shared/embedding.py:19-20` | medium | 1 | audit | +| F-14 | `git clone` receives the repository URL with no `--` separator, so a URL beginning with `-` is parsed as an option. Gateway validation is the only defence; the worker has none | `apps/worker/src/dcode_worker/stages/clone.py:22` | medium | 5 | audit | +| F-15 | The `grep` tool runs `rg` with no timeout and buffers all output in memory; the pure-Python fallback compiles a user-supplied regex with no timeout | `apps/agent/src/dcode_agent/tools/grep.py:44-58`, `:79-101` | medium | 5 | audit | +| F-16 | nginx serves the bundle uncompressed — gzip is commented out in the base image and not enabled in the site config. Main chunk 752.53 kB / 226.74 kB gzipped | `apps/frontend/nginx.conf` | low | 4 | **direct** | +| F-17 | No `.dockerignore` anywhere; the frontend build context ships 227 MB of `node_modules` | repository root | low | 4 | **direct** | +| F-18 | Model sidecars download weights from Hugging Face at runtime with no cache volume | `infra/docker/embedding.Dockerfile`, `infra/docker/reranker.Dockerfile` | low | — | **direct** | + +F-18 is recorded but **not scheduled**: D-1 removes the sidecars from the +deployment path, so it only affects local Docker-profile use. It is left as a +known cost of that mode rather than fixed speculatively. + +### Already correct, recorded so nobody "fixes" it + +- SSE anti-buffering headers are set on both hops — `Cache-Control: no-cache` and + `X-Accel-Buffering: no` at `apps/api/src/dcode_api/routes/query.py:43-44` and + `apps/agent/src/dcode_agent/main.py:108`. R-2 is a platform *timeout*, not a + buffering problem, and does not indicate these are wrong. +- Agent path handling is sound: `normalize_repo_relative_path` rejects absolute + and `..`-escaping paths and the resolved path is re-checked against the root + (`apps/agent/src/dcode_agent/tools/common.py:46-76`). +- In the production topology the `api` service publishes no host port and nginx + proxies only `location /api/`, so `/internal/*` is not reachable from outside. + +--- + +## 8. New Environment Variables + +Added by this workstream. Every one defaults to current behaviour. + +| Variable | Default | Read by | Purpose | +|---|---|---|---| +| `EMBEDDING_PROVIDER` | `sidecar` | api, worker | `sidecar` \| `jina_api` | +| `EMBEDDING_API_KEY` | `""` | api, worker | Required when the provider is not `sidecar` | +| `RERANKER_PROVIDER` | `sidecar` | api | `sidecar` \| `siliconflow` | +| `RERANKER_API_KEY` | `""` | api | Required when the provider is not `sidecar` | +| `AUTH_USERNAME` | — | api | Demo account name | +| `AUTH_PASSWORD_HASH` | — | api | Hash, never a plaintext password | +| `AUTH_SESSION_SECRET` | — | api | Cookie signing key | +| `AUTH_DAILY_QUERY_LIMIT` | (to set) | api | Per-session spend guard | +| `AGENT_REQUEST_BUDGET_SECONDS` | (to set) | agent | R-2 hard ceiling | +| `SSE_HEARTBEAT_SECONDS` | (to set) | api, agent | R-2 keep-alive interval | +| `DOCS_ENABLED` | `false` in production | api | F-05 | + +`EMBEDDING_DIM` keeps its existing meaning and its existing trap: it is fixed +into the pgvector column at migration time. Changing it requires a fresh volume. +Switching providers is now a one-line edit, which makes that trap *easier* to +trigger than it was when it required starting a sidecar. + +`JUDGE_MODEL` is passed by both Compose files and defined in settings but is +referenced by no code. It is left alone here; removing dead configuration is a +product decision, not a deployment one. + +--- + +## 9. Cost + +Order-of-magnitude only. No figure here is measured, and none should be quoted +as if it were. + +- **Embedding** is paid once per index, not per query. Jina offers a free tier, + and the corpus is small — the chunk count of the indexed `psf/requests` + snapshot is recorded in [`docs/en/Operations.md`](docs/en/Operations.md), not + restated here. +- **Reranking** runs per query over a candidate list capped by + `RERANKER_CANDIDATE_LIMIT` (default 16). +- **Synthesis** is one `gpt-4o-mini` call per query, bounded by + `SYNTHESIS_MAX_TOKENS` (default 700) with an input side bounded by a 10-item + evidence budget. A follow-up question costs a second, smaller call. +- **Railway** bills six services by usage; an idle gated demo is small. + +The real exposure is not the unit price — it is an unbounded number of calls. +D-2 removes anonymous callers; `AUTH_DAILY_QUERY_LIMIT` bounds authenticated +ones. Both are required. + +--- + +## 10. Verification Checklist + +Two limits of this environment apply to every claim made about this work, and +neither is a reason to soften a report: + +- **Headless screenshots do not work.** Anything visual is confirmed by a human + in a real browser, or it is reported as unconfirmed. Say what to look at. +- **There is no automated end-to-end test spanning browser and live backend.** + +Before calling the deployment done: + +| # | Check | How | +|---|---|---| +| 1 | Vectors in the deployed database are 768-dimensional and non-zero | `SELECT vector_dims(embedding), left(embedding::text, 20) FROM chunks LIMIT 1;` | +| 2 | The reranker is actually reordering, not passing through | Compare `score_components` on a query with and without rerank | +| 3 | `api` and `agent-worker` agree on embedding configuration | § 5.4 readiness check reports ready | +| 4 | A query streams to completion without being cut | Watch a full run; confirm no truncation at 5 minutes (R-2) | +| 5 | Citations are verified and clickable, and open real indexed source at the cited line | Human, in a browser | +| 6 | Call-graph neighbours are clickable and chain | Human, in a browser | +| 7 | Unauthenticated access to `/workbench` and to each protected route is refused | Private window | +| 8 | `/` and `/methodology` load without a session, and their figures match `results/` | `python3 scripts/sync_eval_artifacts.py --check` | +| 9 | The four local modes in § 5.1 all still start | Locally, after the final PR | + +--- + +## 11. Open Questions + +Carried here rather than answered by assumption. + +1. **Provider client shape** — explicit `jina_api` / `siliconflow` branches, or a + generic OpenAI-compatible adapter layer? The explicit form is less code and + states its intent; the generic form survives a provider change without code. + *Not decided.* +2. **Single shared account, or per-reviewer accounts?** A single account needs no + user table and no migration. *Not decided.* +3. **Team ownership.** `README.md` assigns "infrastructure, deployment" to a + different team member, and `origin` carries four `yuxin_*` branches. This plan + should be reconciled with them before PR 4. *Not resolved.* +4. **Whether `v1.0-submission` is pushed to `origin`.** The tag exists locally + only; pushing it is visible to the whole team. *Not done.* +5. **Long-term fix for R-1.** Merging agent and worker is a workaround. The + durable answer is to stop reading repository source from a shared filesystem — + store file contents in Postgres and have the agent's file tools read from + there. That is a migration plus three tool rewrites, deliberately out of scope + here. *Deferred, recorded.* From d162426af06a6c998b2a074fb33f19c6fccc7e7b Mon Sep 17 00:00:00 2001 From: odieyang <520yangziqi@gmail.com> Date: Sun, 2 Aug 2026 19:02:52 -0700 Subject: [PATCH 2/2] docs(deploy): resolve the two open questions that blocked PR 2 and PR 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit D-5: explicit per-provider client classes rather than a generic OpenAI-compatible adapter. Neither Jina's embeddings response nor SiliconFlow's rerank response is OpenAI-shaped in the part that matters — both carry per-item indices that have to be mapped back to input order — so a shared abstraction would have to model the difference anyway. The cost is recorded: a fourth provider later means writing a class, not setting a variable. D-6: one shared account read from the environment. No user table, no migration. The consequences are written down rather than discovered later: the daily query cap becomes per session rather than per person, and a shared password cannot be revoked for one holder, only rotated. That is adequate for a gated demo and is not an authorization model. Open questions drop from five to two. Team ownership stays unresolved and is the reason this branch is being pushed; the durable fix for the Railway shared-volume constraint stays deferred and recorded. --- Deploy.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Deploy.md b/Deploy.md index 997b716..85de44f 100644 --- a/Deploy.md +++ b/Deploy.md @@ -40,6 +40,8 @@ Recorded so a later reader can see what was chosen and what it ruled out. | D-2 | **Not publicly accessible.** A username/password gate sits between the landing page and the workbench | 2026-08-02 | Removes the anonymous-abuse surface (F-01, F-03 below) as a launch blocker. Landing and `/methodology` stay public; the product does not. | | D-3 | **Deploy to Railway** | 2026-08-02 | TLS, certificates and a public hostname are solved by the platform. Two platform constraints in § 3 change the topology. | | D-4 | **No fork. `Deploy` is a normal feature branch, merged back to `main` in slices** | 2026-08-02 | See § 5.5. | +| D-5 | **Explicit per-provider client classes**, not a generic OpenAI-compatible adapter layer | 2026-08-02 | Less code, and the wire contract of each provider is visible at its call site instead of hidden behind a shape that fits none of them exactly. Cost: adding a fourth provider later means writing a class, not setting a variable. Accepted. | +| D-6 | **One shared account**, not per-reviewer accounts | 2026-08-02 | No user table, no migration, no account lifecycle. The daily query cap in PR 3 is therefore per *session*, not per person, and a shared password cannot be revoked for one holder — rotate it instead. Adequate for a gated demo; not an authorization model. | Decisions still open are in § 11. @@ -285,6 +287,11 @@ The capability behind D-1. mapped back to input order before returning. - Select with `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER`, default `sidecar` (§ 5.2). Add `EMBEDDING_API_KEY` / `RERANKER_API_KEY`. +- Per D-5 these are **two concrete classes with the provider's own payload shape + written out**, not a generic adapter parameterised by field names. Neither + provider is OpenAI-compatible in the part that matters — the response carries + per-item indices that must be mapped back — so a shared abstraction would have + to model the difference anyway. - Timeouts and retries appropriate to a hosted API, not to a cold local model. **Acceptance.** @@ -304,9 +311,9 @@ The capability behind D-1. D-2. Also closes F-01 and F-03. - `POST /api/v1/auth/login`, `POST /api/v1/auth/logout`, `GET /api/v1/auth/me`. - Credentials from environment (password stored as a hash, never plaintext in the - repo or in a committed file). Signed, `HttpOnly`, `Secure`, `SameSite=Lax` - cookie. + Per D-6, **one shared account read from the environment** — no user table, no + migration. The password is stored as a hash, never as plaintext in the repo or + in a committed file. Signed, `HttpOnly`, `Secure`, `SameSite=Lax` cookie. - A dependency on the `repos`, `query` and `inspector` routers (`apps/api/src/dcode_api/main.py:45-47`). `/healthz` stays open. - Frontend `/login` route; `/workbench` checks the session and redirects on 401. @@ -489,18 +496,11 @@ Before calling the deployment done: Carried here rather than answered by assumption. -1. **Provider client shape** — explicit `jina_api` / `siliconflow` branches, or a - generic OpenAI-compatible adapter layer? The explicit form is less code and - states its intent; the generic form survives a provider change without code. - *Not decided.* -2. **Single shared account, or per-reviewer accounts?** A single account needs no - user table and no migration. *Not decided.* -3. **Team ownership.** `README.md` assigns "infrastructure, deployment" to a +1. **Team ownership.** `README.md` assigns "infrastructure, deployment" to a different team member, and `origin` carries four `yuxin_*` branches. This plan - should be reconciled with them before PR 4. *Not resolved.* -4. **Whether `v1.0-submission` is pushed to `origin`.** The tag exists locally - only; pushing it is visible to the whole team. *Not done.* -5. **Long-term fix for R-1.** Merging agent and worker is a workaround. The + should be reconciled with them before PR 4. *Not resolved.* Pushing `Deploy` + and `v1.0-submission` makes it visible to them, which is the point. +2. **Long-term fix for R-1.** Merging agent and worker is a workaround. The durable answer is to stop reading repository source from a shared filesystem — store file contents in Postgres and have the agent's file tools read from there. That is a migration plus three tool rewrites, deliberately out of scope