Wire/API compatibility — Koder Flow vs upstream Forgejo
Normative contract for the wire/API surfaces Koder Flow promises to keep byte- or semantically-equivalent with the upstream Forgejo it forks. Flow ships the same wire as Forgejo but never CI-proves it (koder.toml gates_pending=cross_impl_tests); every Koder-side delta therefore risks silently diverging from upstream and breaking external tools (`gh`, Forgejo/Gitea clients, repo mirroring, package clients) that depend on shared semantics. This spec pins WHICH surfaces are contractual, what "equivalent" means per surface, and the replay-diff harness that gates the promise in CI.
Koder Flow is a Forgejo derivative (GPL-3.0-or-later, see koder.toml). It inherits Forgejo's HTTP API, git wire protocol, and package-registry HTTP surfaces, and ships Koder-specific additions on top (Koder ID OAuth consumer, branding, a handful of routers). The value of staying a compatible fork is that the whole external ecosystem — gh, Forgejo/Gitea API clients, git itself, mirroring tools, helmdockernpm/cargo package clients — keeps working unchanged against flow.koder.dev.
That compatibility is currently asserted but never proven. This spec defines the contractual surface, the equivalence rules per surface, and the replay-diff harness that turns the promise into a CI gate (closing koder.toml gates_pending=cross_impl_tests).
Scope
This spec governs only the surfaces below. Koder-specific additions (Koder ID OAuth, custom templates, branding) are explicitly out of contract — they may diverge from Forgejo freely, but they MUST NOT alter the shape of an in-contract surface for a request that does not opt into them.
R1 — Contractual surfaces
The following surfaces are contractual — Flow promises equivalence (per the rules in R2) with the upstream Forgejo release pinned in R5:
| ID | Surface | Equivalence class (R2) |
|---|---|---|
| S1 | GET /api/v1/version |
semantic (version string differs; shape pinned) |
| S2 | `apiv1/repos |