KVS — Koder Version System

  • Area: Developer Platform
  • Path: products/dev/kvs
  • Kind: Unified version-control product — a concurrent-commit client (CLI) + a concurrent, AI-first git forge host (the Koder Flow / Gitea successor)
  • Tagline: Version control built for many hands — humans and agents — at once.
  • Status: client v1.x dev-validated (fleet default commit mechanism); host walking-skeleton COMPLETE in dev (built + end-to-end tested on dev-linux-kvs over real Postgres + git), pre-production. RFC: rfcs/kvs-RFC-002-concurrent-ai-first-forge-on-kdb.kmd (ratified 2026-06-10).

Role in the stack

KVS is Koder's next-generation version system — one product with two faces:

  1. Client — the kvs wc concurrent-commit CLI. It is the *efault commit

    mechanism for every concurrent session (KVS#202): it commits against a per-operation temp index (GIT_INDEX_FILE), path-scoped, eliminating the shared .git/index hazard that the old git commit -o + per-component lock discipline existed to work around. AST/block merge (#206) lets independent edits to the same file land without spurious conflicts. The client also ships a local-repo web dashboard*(internal/web/, kvs web): statuslogdiffbranchesanalytics plus persistent code-review comments (.kvs/reviews.json), forge PR listcreatemerge (reusing the internal/flow Gitea-compatible client), realtime updates over SSE, a 3-way merge-conflict resolver (internal/core/conflict), forge auth surfacing, and multi-repo switching (active repo scoped via core.Workdir) — KVS-271.

  1. Host — a concurrent, AI-first git forge (kvs-RFC-002), the successor to

    Koder Flow (a Gitea/Forgejo fork). It removes Flow's rigid two-level org → repo structure and its single-writer push model, and is the long-term home for Koder's repositories once it reaches production.

The two faces share the name because they share the thesis: version control should support extreme concurrency — many humans and AI agents writing the same repositories at once — without serialization.

Why a new forge (vs. Koder Flow)

Flow (Forgejo) imposes a mandatory organization → repository hierarchy and rejects non-fast-forward pushes (the standard git single-writer model). KVS-host fixes both:

  • Flexible recursive namespaces — a node may contain child namespaces and

    repos to arbitrary depth (no privileged "org" level). Permissions resolve through the tree (nearest-ancestor-wins + explicit deny); a root namespace is a tenant boundary. Spec: specs/kvs/namespace-tree.kmd.

  • Lock-free, auto-merging concurrent push (the differentiator) — N agents can

    git push the same branch concurrently and all land with zero non-fast-forward rejections; the server three-way auto-merges divergent pushes, and a true conflict is committed as first-class needs-resolution data (never rejected, never silently overwritten). Spec: specs/kvs/concurrent-merge.kmd.

  • AI-first — a Model-Context-Protocol surface (resources + tools) is a co-equal

    access path alongside git and the web UI, so agents are first-class subjects.

Host architecture (products/dev/kvs/internal/host/)

Package Responsibility
namespace Recursive namespace-tree domain + permission resolution; in-memory MemStore (unit) + kdb-next/pgwire PGStore with FORCE Row-Level Security (multi-tenant isolation at the data plane).
auth The authn+authz seam: Claims → Authn, the Guard decision point (R4 grants + R5 visibility read-baseline), and SDKVerifier (reuses engines/sdk/go/auth for Koder ID OIDC introspection).
githttp git smart-HTTP via shell-out (git upload-pack/receive-pack); swappable on-disk repo store (DiskStore).
merge The concurrent-merge engine — optimistic CAS ref advance + three-way auto-merge + conflict-as-committable-object. The differentiator.
vbranch Virtual branches (KVS-274) — named lanes under `refskvsvbranch