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/3] 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/3] 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 From c0a9fdabfe4bb622145dceb75247e563173880dd Mon Sep 17 00:00:00 2001 From: odieyang <520yangziqi@gmail.com> Date: Sun, 2 Aug 2026 19:14:42 -0700 Subject: [PATCH 3/3] fix(deploy): give every service the retrieval settings it reads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The production compose file configured almost none of the retrieval stack, and the failure mode is silence rather than an error. The api service had no embedding or reranker configuration at all. Two consequences. `make prod-migrate` runs alembic inside that container, and 001_initial_schema reads shared_settings.embedding_dim to size the pgvector column — so production built a vector(1024) column whatever .env.production said, while the worker inserted at its own configured dimension. And the api is the service that embeds the search query and reranks candidates, so it silently ran the stub path: an all-zero query vector against real stored vectors, which is dense retrieval returning noise with nothing in the log. The other two services were short as well. The worker had a model and a dimension but no EMBEDDING_ENDPOINT, so it could not reach a service. The agent had RERANKER_ENDPOINT alone, which selects nothing — create_reranker_ client returns None for a stub model regardless of the endpoint — so the evidence-union rerank the agent performs was identity ordering in production. EMBEDDING_DIM is now required in production rather than defaulted. It is not only the migration that depends on it: dcode_shared.db.models binds the chunks.embedding column type at import time, so every service touching the ORM needs it right. A wrong value is a re-index, not a slow query, and that is not a thing to inherit from a default that happens to suit stub vectors. Also here: the dead RERANKER_ENDPOINT=http://localhost:9999 default is replaced by an empty one, which fails loudly for a real model and is ignored by a stub; the two documented compose invocations are reconciled on the standalone form, because the overlay form the env example documented republishes Postgres, Redis and the RabbitMQ UI to the host. EMBEDDING_TIMEOUT_SECONDS becomes env-tunable instead of hardcoded at 300s. The value is unchanged. Twelve retries against a 300s timeout can hold one batch for about an hour while prefetch_count=1 stalls the queue behind it, but those defaults are correct for a cold CPU sidecar; the path they are wrong for is the hosted API, which does not exist until PR 2. PR 2 sets them. Three tests pin all of this, and each was confirmed to fail when its defect is put back. They parse the compose file by hand rather than importing PyYAML, which is only a transitive dependency here and is imported by no other code in the repository. Deploy.md records a correction: F-02 was written as "the api service has no embedding configuration" and was wider than that. The register and the acceptance criteria are updated from what was observed, not from what was planned. --- .env.example | 3 + .env.production.example | 83 +++++++++++-- Deploy.md | 58 ++++++--- README.md | 17 ++- apps/api/src/dcode_api/routes/internal.py | 1 + apps/worker/src/dcode_worker/stages/embed.py | 1 + docker-compose.prod.yml | 34 +++++- docker-compose.yml | 2 + packages/shared/src/dcode_shared/embedding.py | 2 + packages/shared/src/dcode_shared/settings.py | 8 ++ .../shared/tests/test_config_hardening.py | 110 ++++++++++++++++++ 11 files changed, 289 insertions(+), 30 deletions(-) diff --git a/.env.example b/.env.example index 3797cd4..f894d1b 100644 --- a/.env.example +++ b/.env.example @@ -48,6 +48,9 @@ EMBEDDING_DIM=1024 # EMBEDDING_ENDPOINT=http://host.docker.internal:8002 # EMBEDDING_BATCH_SIZE=1 # EMBEDDING_MAX_SEQ_LENGTH=1024 # caps Jina token window to avoid OOM (0 = disable) +# EMBEDDING_MAX_RETRIES=12 # sized for a cold CPU sidecar, not for an API +# EMBEDDING_TIMEOUT_SECONDS=300 # ditto — their product is the worst-case stall, +# # and the worker consumes one job at a time # On MacBook: run `make embedding-host` in a separate terminal (recommended). # Or Docker sidecar: docker compose --profile embedding up -d embedding # If you change EMBEDDING_DIM after first migrate: make down-all && make migrate diff --git a/.env.production.example b/.env.production.example index f443cc2..c106a70 100644 --- a/.env.production.example +++ b/.env.production.example @@ -1,8 +1,15 @@ # ============================================================ # Dcode production environment variables. -# Copy to `.env.production` on the deployment host and review -# every placeholder before `docker compose -f docker-compose.yml -# -f docker-compose.prod.yml up -d --build`. +# +# Copy to `.env.production` on the deployment host and review every +# placeholder before: +# +# docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +# +# `docker-compose.prod.yml` is a COMPLETE stack, not an overlay. Do not +# combine it with `-f docker-compose.yml`: the developer file publishes +# Postgres, Redis and the RabbitMQ management UI to the host, and overlaying +# would republish them on a public machine. # ============================================================ # --- Public entrypoint --- @@ -13,26 +20,82 @@ PUBLIC_ORIGIN=http://dcode.odieyang.com POSTGRES_USER=dcode POSTGRES_PASSWORD=__SET_PROD_POSTGRES_PASSWORD__ POSTGRES_DB=dcode -DATABASE_URL=postgresql+asyncpg://dcode:__SET_PROD_POSTGRES_PASSWORD__@postgres:5432/dcode # --- Internal services --- -REDIS_URL=redis://redis:6379/0 RABBITMQ_USER=__SET_PROD_RABBITMQ_USER__ RABBITMQ_PASSWORD=__SET_PROD_RABBITMQ_PASSWORD__ + +# The compose file builds DATABASE_URL / REDIS_URL / RABBITMQ_URL / AGENT_URL +# from the values above and the internal service names, so these four are NOT +# read by the running stack. They are here for commands run against this env +# file outside compose (an alembic invocation on the host, for example). If you +# change a credential above, change it here too or leave these out entirely. +DATABASE_URL=postgresql+asyncpg://dcode:__SET_PROD_POSTGRES_PASSWORD__@postgres:5432/dcode +REDIS_URL=redis://redis:6379/0 RABBITMQ_URL=amqp://__SET_PROD_RABBITMQ_USER__:__SET_PROD_RABBITMQ_PASSWORD__@rabbitmq:5672/ AGENT_URL=http://agent:8001 # --- Internal service auth --- +# Protects every /internal/* retrieval and graph route. The code default is a +# placeholder published in this repository, so this must be set to a real +# secret — the compose file refuses to start without it. INTERNAL_API_KEY=__SET_PROD_INTERNAL_API_KEY__ -# --- Model / runtime knobs --- -# Production defaults keep model serving disabled. If production should use -# real embedding/reranker services, add those services to the deployment and -# set endpoint, model, and EMBEDDING_DIM consistently before indexing. LOG_LEVEL=info + +# ============================================================ +# Retrieval models +# +# These are read by api, worker AND agent, and they must AGREE. The API embeds +# the search query, the worker embeds the corpus, and the agent reranks its own +# evidence union. Configuring one service and not another produces no error — +# it produces real vectors in the database being searched with a stub all-zero +# query vector, i.e. dense retrieval silently returning noise. +# ============================================================ + +# EMBEDDING_DIM is fixed into the pgvector column by the migration and cannot +# be changed afterwards without a new volume. It has no default in production +# for that reason: a wrong value here is not a slow query, it is a re-index. +# stub = 1024 zero vectors; jinaai/jina-embeddings-v2-base-code = 768. EMBEDDING_MODEL=stub EMBEDDING_DIM=1024 EMBEDDING_ENDPOINT= + +# Sized for a cold self-hosted sidecar. 12 retries against a 300s timeout can +# hold one batch of four chunks for about an hour, and the worker consumes one +# job at a time, so everything queued behind it waits. Lower both substantially +# when the endpoint is a hosted API rather than a model loading on CPU. +# EMBEDDING_BATCH_SIZE=4 +# EMBEDDING_MAX_RETRIES=12 +# EMBEDDING_TIMEOUT_SECONDS=300 + +# Leave RERANKER_ENDPOINT empty unless RERANKER_MODEL is a real model. A +# non-stub model with an empty endpoint fails fast and loudly, which is the +# intended behaviour; a stub model ignores the endpoint entirely. RERANKER_MODEL=stub -RERANKER_ENDPOINT=http://localhost:9999 +RERANKER_ENDPOINT= +# RERANKER_CANDIDATE_LIMIT=16 +# RERANKER_MAX_RETRIES=3 + +# Hybrid RRF fusion weights. Dense above sparse reduces keyword noise. +# RRF_DENSE_WEIGHT=2.0 +# RRF_SPARSE_WEIGHT=1.0 + +# ============================================================ +# Answer synthesis +# ============================================================ + +# 'stub' keeps rule-based template answers. Set an OpenAI-compatible model and +# key for prose answers; citations are verified against the index either way. +SYNTHESIS_MODEL=stub +OPENAI_API_KEY= +OPENAI_BASE_URL= +# SYNTHESIS_MAX_TOKENS=700 +# SYNTHESIS_TEMPERATURE=0.1 + +# Keep above 0 in production so the groundedness guardrail stays enforced. +# GROUNDEDNESS_THRESHOLD=0.95 + +# Defined and passed through, but read by no code today. Left in place rather +# than removed, because removing dead configuration is a product decision. JUDGE_MODEL=stub diff --git a/Deploy.md b/Deploy.md index 85de44f..f7bb037 100644 --- a/Deploy.md +++ b/Deploy.md @@ -25,8 +25,9 @@ Outstanding Work list in the same PR, not tracked in two places. 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`). +**Status: PR 1 of 5 landed; PR 2–5 not started.** The pre-deployment state is +frozen at tag `v1.0-submission` (`a4612b8`). Nothing is deployed anywhere yet, +and no live model API has been called from this codebase. --- @@ -254,21 +255,46 @@ revertable, and must pass `make check` and `make frontend-build` on its own. it is done when its criteria are demonstrated, and honestly reported when they are not. -### PR 1 — `fix/prod-compose-model-env` +### PR 1 — `fix/prod-compose-model-env` — **done** 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. | +| Item | Detail | Outcome | +|---|---|---| +| F-02 | Give every service the retrieval settings it reads. See the correction below — this was wider than "the `api` service". | done | +| F-11 | Reconcile the two documented Compose invocations: `README.md:324` used `-f docker-compose.prod.yml` alone; `.env.production.example:4-5` documented overlaying it on `docker-compose.yml`, which republishes Postgres, Redis and the RabbitMQ management UI to the host. | done — standalone form, and both files now say so | +| F-12 | Remove the dead `RERANKER_ENDPOINT=http://localhost:9999` default. | done — empty default, which fails loudly for a real model and is ignored by a stub | +| F-13 | `max_retries=12` against a hardcoded 300 s timeout (`embedding.py:19-20`) can occupy one batch of four chunks for roughly an hour while `prefetch_count=1` stalls the queue behind it. | **partially done** — the timeout is now env-tunable (`EMBEDDING_TIMEOUT_SECONDS`) instead of hardcoded; the *values* are unchanged, because the defaults are correct for a cold CPU sidecar and the hosted-API path they are wrong for does not exist until PR 2. PR 2 sets them. | -**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. +**Correction: F-02 was under-described in the original plan.** It was written as +"the `api` service has no embedding configuration". Reading what each service +actually reads showed all three were short: + +| Service | Was missing | +|---|---| +| `api` | every retrieval setting — all twelve | +| `worker` | `EMBEDDING_ENDPOINT`, `EMBEDDING_BATCH_SIZE`, `EMBEDDING_MAX_RETRIES` — so it had a model and a dimension but no way to reach a service | +| `agent` | `RERANKER_MODEL`, `RERANKER_MAX_RETRIES`, `EMBEDDING_DIM`, and the synthesis knobs. It had `RERANKER_ENDPOINT` alone, which selects nothing: `create_reranker_client` returns `None` for a stub model whatever the endpoint says (`packages/shared/src/dcode_shared/reranker.py:119-120`) | + +`EMBEDDING_DIM` also turned out to matter more widely than the migration. +`dcode_shared.db.models:128` binds the `chunks.embedding` column type to it at +**import time**, so every service that touches the ORM needs it correct, not just +the one that runs Alembic. It is now required in production (`${EMBEDDING_DIM:?…}`) +rather than defaulted, because a wrong value there is a re-index, not a slow query. + +**Acceptance — met.** + +1. `docker compose --env-file .env.production.example -f docker-compose.prod.yml config` + resolves 12 retrieval variables on `api`, 6 on `worker`, 9 on `agent`, all + mutually consistent. Observed. +2. Omitting `EMBEDDING_DIM` aborts the config with the reason attached rather + than silently defaulting. Observed. +3. `make check` green: ruff, eslint, the eval-artifact drift check, mypy strict + over 83 source files, 289 passed / 5 skipped in pytest, 73 frontend tests. +4. Three new tests in `packages/shared/tests/test_config_hardening.py` pin all + of the above, and **each was confirmed to fail when its defect is put back** — + a config test that has never been seen failing is not evidence of anything. ### PR 2 — `feat/managed-model-providers` @@ -380,7 +406,7 @@ 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-02 | ~~The `api` service in the production Compose file has no embedding or reranker configuration~~ **— fixed in PR 1, and it was wider than this row said: `worker` and `agent` were short too. See § 6 PR 1.** | `docker-compose.prod.yml` | 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 | @@ -389,9 +415,9 @@ as leads to verify when the PR touches them, not as established fact. | 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-11 | ~~The two documented production Compose invocations disagree; one of them republishes Postgres, Redis and the RabbitMQ UI~~ **— fixed in PR 1.** | `README.md`, `.env.production.example` | medium | 1 | **direct** | +| F-12 | ~~`RERANKER_ENDPOINT` defaults to a dead loopback address in the production template~~ **— fixed in PR 1, pinned by a test.** | `docker-compose.prod.yml`, `.env.production.example` | 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. **Knob added in PR 1 (`EMBEDDING_TIMEOUT_SECONDS`); the values are set in PR 2, where the path that needs them exists.** | `packages/shared/src/dcode_shared/embedding.py:19-20` | medium | 1 → 2 | 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** | diff --git a/README.md b/README.md index 58a9768..4734539 100644 --- a/README.md +++ b/README.md @@ -326,8 +326,19 @@ docker compose --env-file .env.production -f docker-compose.prod.yml exec api \ uv run alembic -c infra/migrations/alembic.ini upgrade head ``` +`docker-compose.prod.yml` is a complete stack, **not an overlay**. Combining it +with `-f docker-compose.yml` republishes Postgres, Redis and the RabbitMQ +management UI to the host. + +Every service that touches retrieval — api, worker and agent — reads the same +embedding and reranker configuration, and they must agree. `EMBEDDING_DIM` has +no production default on purpose: the migration bakes it into the pgvector +column, so a wrong value is a re-index rather than a slow query. + The production stack is validated locally only — `dcode.odieyang.com` does **not** -resolve publicly, so the external-demo exit criterion is still open. +resolve publicly, so the external-demo exit criterion is still open. The plan for +closing it, including the platform constraints that shape it, is +[`Deploy.md`](Deploy.md). --- @@ -474,7 +485,8 @@ H1 could be evaluated with a simpler indexing script; the queue, worker, state m ## Documentation -Five documents. `docs/en/` is authoritative. +Six documents. `docs/en/` is authoritative; [`Deploy.md`](Deploy.md) sits at the +root because it governs an in-flight workstream rather than the delivered system. | Document | Contents | |---|---| @@ -483,6 +495,7 @@ Five documents. `docs/en/` is authoritative. | **[`docs/en/Technical_Design.md`](docs/en/Technical_Design.md)** | Technical authority: repository layout, architecture, service boundaries, data model, API contracts, NFRs, technology choices | | **[`docs/en/Operations.md`](docs/en/Operations.md)** | Running the stack, the real-model path, the evaluation harness, and the operational gotchas worth knowing before you hit them | | **[`docs/en/Agentic_Workflow.md`](docs/en/Agentic_Workflow.md)** | How Claude Code, Codex, and Cursor were cross checked during development | +| **[`Deploy.md`](Deploy.md)** | Taking this online: decisions taken, verified platform constraints, the invariants, the PR breakdown with acceptance criteria, and a findings register where every row carries a `file:line` | Colocated with what they describe: [`results/README.md`](results/README.md) (which recorded run is the current conclusion), [`design/README.md`](design/README.md) diff --git a/apps/api/src/dcode_api/routes/internal.py b/apps/api/src/dcode_api/routes/internal.py index 1237b1e..a0b52be 100644 --- a/apps/api/src/dcode_api/routes/internal.py +++ b/apps/api/src/dcode_api/routes/internal.py @@ -370,6 +370,7 @@ def _get_query_embedding_client() -> EmbeddingClient: endpoint=api_settings.embedding_endpoint, batch_size=api_settings.embedding_batch_size, max_retries=api_settings.embedding_max_retries, + timeout_seconds=api_settings.embedding_timeout_seconds, ) return _query_embedding_client diff --git a/apps/worker/src/dcode_worker/stages/embed.py b/apps/worker/src/dcode_worker/stages/embed.py index 646c399..d60cb3a 100644 --- a/apps/worker/src/dcode_worker/stages/embed.py +++ b/apps/worker/src/dcode_worker/stages/embed.py @@ -53,6 +53,7 @@ async def run( endpoint=worker_settings.embedding_endpoint, batch_size=worker_settings.embedding_batch_size, max_retries=worker_settings.embedding_max_retries, + timeout_seconds=worker_settings.embedding_timeout_seconds, ) owns_redis = redis_client is None diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index 0e43fb7..2691ea8 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -51,6 +51,22 @@ services: AGENT_URL: http://agent:8001 CORS_ORIGINS: ${PUBLIC_ORIGIN:-http://dcode.odieyang.com} INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} + # The API embeds the query and reranks candidates at search time, so it + # needs the same retrieval configuration as the worker — not a subset. + # It is also where `make prod-migrate` runs, and the migration reads + # EMBEDDING_DIM to size the pgvector column. + EMBEDDING_MODEL: ${EMBEDDING_MODEL:-stub} + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it is fixed into the pgvector column at migration time and cannot be changed without a new volume} + EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-} + EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} + EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} + RRF_DENSE_WEIGHT: ${RRF_DENSE_WEIGHT:-2.0} + RRF_SPARSE_WEIGHT: ${RRF_SPARSE_WEIGHT:-1.0} + RERANKER_MODEL: ${RERANKER_MODEL:-stub} + RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-} + RERANKER_CANDIDATE_LIMIT: ${RERANKER_CANDIDATE_LIMIT:-16} + RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3} LOG_LEVEL: ${LOG_LEVEL:-info} depends_on: postgres: @@ -75,7 +91,11 @@ services: REDIS_URL: redis://redis:6379/0 RABBITMQ_URL: amqp://${RABBITMQ_USER:?set RABBITMQ_USER in .env.production}:${RABBITMQ_PASSWORD:?set RABBITMQ_PASSWORD in .env.production}@rabbitmq:5672/ EMBEDDING_MODEL: ${EMBEDDING_MODEL:-stub} - EMBEDDING_DIM: ${EMBEDDING_DIM:-1024} + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it must equal the dimension the volume was migrated at} + EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-} + EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} + EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} LOG_LEVEL: ${LOG_LEVEL:-info} @@ -107,7 +127,17 @@ services: SYNTHESIS_MODEL: ${SYNTHESIS_MODEL:-stub} OPENAI_API_KEY: ${OPENAI_API_KEY:-} OPENAI_BASE_URL: ${OPENAI_BASE_URL:-} - RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-http://localhost:9999} + SYNTHESIS_MAX_TOKENS: ${SYNTHESIS_MAX_TOKENS:-700} + SYNTHESIS_TEMPERATURE: ${SYNTHESIS_TEMPERATURE:-0.1} + # The agent reranks its own evidence union, so it needs the reranker + # configuration too — RERANKER_ENDPOINT alone selected nothing, because + # a stub RERANKER_MODEL returns no client regardless of the endpoint. + RERANKER_MODEL: ${RERANKER_MODEL:-stub} + RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-} + RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3} + # Not read directly by the agent, but dcode_shared.db.models binds the + # chunks.embedding column type to it at import time. + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it must equal the dimension the volume was migrated at} RETRIEVAL_BASE_URL: http://api:8000 WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} diff --git a/docker-compose.yml b/docker-compose.yml index 4451181..065b726 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -61,6 +61,7 @@ services: EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-http://host.docker.internal:8002} EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} RRF_DENSE_WEIGHT: ${RRF_DENSE_WEIGHT:-2.0} RRF_SPARSE_WEIGHT: ${RRF_SPARSE_WEIGHT:-1.0} RERANKER_MODEL: ${RERANKER_MODEL:-stub} @@ -97,6 +98,7 @@ services: EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-http://host.docker.internal:8002} EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env} LOG_LEVEL: ${LOG_LEVEL:-info} diff --git a/packages/shared/src/dcode_shared/embedding.py b/packages/shared/src/dcode_shared/embedding.py index af34ef7..bf74c45 100644 --- a/packages/shared/src/dcode_shared/embedding.py +++ b/packages/shared/src/dcode_shared/embedding.py @@ -129,6 +129,7 @@ def create_embedding_client( endpoint: str = "", batch_size: int = _DEFAULT_BATCH_SIZE, max_retries: int = _DEFAULT_MAX_RETRIES, + timeout_seconds: float = _DEFAULT_TIMEOUT_SECONDS, ) -> EmbeddingClient: """Build the embedding client for the current environment.""" if model == "stub": @@ -146,6 +147,7 @@ def create_embedding_client( dim=dim, batch_size=batch_size, max_retries=max_retries, + timeout_seconds=timeout_seconds, ) diff --git a/packages/shared/src/dcode_shared/settings.py b/packages/shared/src/dcode_shared/settings.py index c332927..c1a02b0 100644 --- a/packages/shared/src/dcode_shared/settings.py +++ b/packages/shared/src/dcode_shared/settings.py @@ -46,7 +46,15 @@ class SharedSettings(BaseSettings): embedding_dim: int = 1024 embedding_endpoint: str = "" embedding_batch_size: int = 4 + # The defaults below are sized for a cold self-hosted sidecar: a CPU Jina + # model can take minutes to load, and the retries exist to ride that out. + # Their product is the worst case, and it is long — 12 attempts against a + # 300s read timeout can hold one batch for about an hour while the worker + # (prefetch_count=1) stalls every other queued repository behind it. A + # hosted embedding API fails in seconds and should be configured with much + # smaller values; both are env-tunable so neither path pays the other's cost. embedding_max_retries: int = 12 + embedding_timeout_seconds: float = 300.0 # Weighted RRF for hybrid fusion. Dense gets higher weight because # equal 1:1 RRF lets sparse keyword noise dilute semantic ranking # (observed: B2 dense nDCG > B3 hybrid under equal weights). diff --git a/packages/shared/tests/test_config_hardening.py b/packages/shared/tests/test_config_hardening.py index 1ed07e3..716d998 100644 --- a/packages/shared/tests/test_config_hardening.py +++ b/packages/shared/tests/test_config_hardening.py @@ -1,9 +1,28 @@ """Configuration hardening checks for env examples and compose files.""" +import re from pathlib import Path _ROOT = Path(__file__).resolve().parents[3] +# A compose service block: ` name:` at two spaces, everything under it deeper. +# Parsed by hand rather than with PyYAML, which is only a transitive dependency +# here and is imported by no other code in this repository. +_SERVICE_HEADER = re.compile(r"^ {2}([a-z0-9_-]+):\s*$") + + +def _service_block(compose_text: str, service: str) -> str: + lines = compose_text.splitlines() + starts = [i for i, line in enumerate(lines) if _SERVICE_HEADER.match(line)] + for position, index in enumerate(starts): + match = _SERVICE_HEADER.match(lines[index]) + assert match is not None + if match.group(1) != service: + continue + end = starts[position + 1] if position + 1 < len(starts) else len(lines) + return "\n".join(lines[index:end]) + raise AssertionError(f"service {service!r} not found in compose file") + def test_env_examples_do_not_ship_known_weak_credentials() -> None: env_example = (_ROOT / ".env.example").read_text(encoding="utf-8") @@ -26,3 +45,94 @@ def test_prod_compose_requires_explicit_secret_env_vars() -> None: assert "${POSTGRES_PASSWORD:?" in compose assert "${RABBITMQ_PASSWORD:?" in compose assert "${INTERNAL_API_KEY:?" in compose + + +def test_prod_compose_requires_an_explicit_embedding_dimension() -> None: + """A defaulted EMBEDDING_DIM in production is not a slow query, it is a re-index. + + The migration sizes the pgvector column from this value + (infra/migrations/versions/001_initial_schema.py) and the ORM binds the + column type to it at import time (dcode_shared.db.models). Once the volume + exists the dimension cannot change, so production must state it rather than + inherit the 1024 code default that happens to suit stub vectors. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + + assert "${EMBEDDING_DIM:-" not in compose + assert "${EMBEDDING_DIM:?" in compose + + +def test_prod_services_receive_the_retrieval_settings_they_read() -> None: + """Every service must be able to receive each setting it actually reads. + + Violating this produces no error and no log line. The API embeds the search + query and the worker embeds the corpus; if only one of them is configured, + real vectors get searched with a stub all-zero query vector and dense + retrieval silently returns noise. The production API shipped with none of + these, which also meant `make prod-migrate` built the column at the default + dimension no matter what the env file said. + + The expected sets below are what each service reads today. If a service + starts reading a new setting, add it here as well as to the compose file. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + + expected = { + # dcode_api.routes.internal builds both the query embedding client and + # the query reranker client, and fuses with the RRF weights. + "api": { + "EMBEDDING_MODEL", + "EMBEDDING_DIM", + "EMBEDDING_ENDPOINT", + "EMBEDDING_BATCH_SIZE", + "EMBEDDING_MAX_RETRIES", + "EMBEDDING_TIMEOUT_SECONDS", + "RRF_DENSE_WEIGHT", + "RRF_SPARSE_WEIGHT", + "RERANKER_MODEL", + "RERANKER_ENDPOINT", + "RERANKER_CANDIDATE_LIMIT", + "RERANKER_MAX_RETRIES", + }, + # dcode_worker.stages.embed builds the index-time embedding client. + "worker": { + "EMBEDDING_MODEL", + "EMBEDDING_DIM", + "EMBEDDING_ENDPOINT", + "EMBEDDING_BATCH_SIZE", + "EMBEDDING_MAX_RETRIES", + "EMBEDDING_TIMEOUT_SECONDS", + }, + # dcode_agent.graph reranks its own evidence union; EMBEDDING_DIM is + # not read by the agent directly but binds the ORM column type. + "agent": { + "EMBEDDING_DIM", + "RERANKER_MODEL", + "RERANKER_ENDPOINT", + "RERANKER_MAX_RETRIES", + "SYNTHESIS_MODEL", + "SYNTHESIS_MAX_TOKENS", + "SYNTHESIS_TEMPERATURE", + "GROUNDEDNESS_THRESHOLD", + }, + } + + for service, variables in expected.items(): + block = _service_block(compose, service) + missing = sorted(name for name in variables if f"\n {name}:" not in block) + assert not missing, f"{service} is missing {missing} in docker-compose.prod.yml" + + +def test_no_dead_loopback_endpoints_in_production_config() -> None: + """A reranker endpoint pointing at localhost:9999 inside a container. + + It resolved to nothing, and because RERANKER_MODEL defaulted to stub the + client was never built, so the dead address never produced an error either. + An empty endpoint is the honest default: a real model with no endpoint + raises at construction, and a stub model ignores it. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + env_prod_example = (_ROOT / ".env.production.example").read_text(encoding="utf-8") + + for content in (compose, env_prod_example): + assert "localhost:9999" not in content