Skip to content

docs(deploy): the deployment plan, and the two decisions that unblock it - #18

Merged
Odiethebest merged 2 commits into
mainfrom
Deploy
Aug 3, 2026
Merged

Odiethebest merged 2 commits into
mainfrom
Deploy

Conversation

@Odiethebest

Copy link
Copy Markdown
Owner

Adds Deploy.md — the authority for taking Dcode online — and points CLAUDE.md at it. Docs only; no runtime code changes.

Why a separate document

Deployment turned out to touch three things at once: platform constraints that change the architecture, a handful of real product defects, and two decisions with methodological consequences. Scattering that across commit messages would have lost the reasoning, and putting it in Final_Report.md would have created a second backlog next to Outstanding Work.

Deploy.md covers only what is unfinished in getting it deployed. Where an item is also a product defect — most are — it gets struck from Outstanding Work in the PR that fixes it, not tracked in two places.

What is decided

Decision
D-1 Real models, served by hosted APIs rather than self-hosted sidecars
D-2 Not publicly accessible — a username/password gate between landing and workbench
D-3 Railway
D-4 No fork; Deploy merges back to main in slices
D-5 Explicit per-provider client classes, not a generic adapter layer
D-6 One shared account, not per-reviewer accounts

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 — Jina v2-base-code at 768 dimensions, BGE reranker v2-m3, gpt-4o-mini — are available as hosted APIs, so D-1 can be satisfied without substituting anything. If a future change does substitute one, it says so on the landing page and /methodology or it reverts. §2 also records what parity of model identity does not buy: identical weights through a provider's API are not bit-identical to local serving, so a future H1 re-run through the APIs is a new run directory, not a refresh of the recorded snapshot.

Two Railway constraints that change the architecture

Both verified against Railway's documentation on 2026-08-02 rather than assumed:

  • A volume attaches to exactly one service. repo_workdirs is written by the worker and read by the agent's read_file / grep / list_directory tools, so those two must share one Railway service. This is a platform workaround, recorded as such, with the durable fix (stop reading source from a shared filesystem) deferred and written down.
  • HTTP requests are cut after 5 minutes with no data, ~15 minutes with heartbeats. The agent emits no heartbeats and has no overall request timeout at all.

Findings register

§7 lists 18 findings, each with a file:line. Every 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 as the same kind of claim is how a plan acquires facts nobody verified. §7 also records three things that are already correct, so nobody "fixes" them.

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. Sections renumbered 2–6 → 3–7; the two internal §1 references still resolve.

Verification

make check green. Docs-only change; nothing was deployed and no live model API has been called from this codebase.

Tag v1.0-submission (a4612b8) freezes the pre-deployment state.

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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant