codetree 0.1.2

AI-native version control system for autonomous agents
Documentation
# DESIGN

System design document for CodeTree. Covers design principles, architecture decisions, data model, module boundaries, and rationale.

> For the product definition (what/who/why) see [`PRODUCT.md`]PRODUCT.md.
> For the implementation-level module map and data flow see [`ARCHITECTURE.md`]ARCHITECTURE.md.
> For the command/protocol contract see [`SPEC.md`]SPEC.md.

---

## Design Principles

### 1. Operation-Centric, Not Branch-Centric

The primary unit of work is an **operation** — a task with a description, file scope, lifecycle, and owner. Branches are storage implementation details. Agents think "fix the login bug," not "create branch `codetree_1700000000_fix_login_bug`."

**Implication:** Every command, MCP tool, and data structure is framed in terms of operations. The branch name is auto-generated and opaque.

### 2. Isolation by Default

Operations are **parallel by default** — `start` creates a branch ref without switching to it. The agent's working tree is not disrupted. This allows an orchestrator to spawn many operations without interleaving working-tree state.

**Implication:** `--checkout` is opt-in. Worktrees (`--worktree`) provide physical isolation when needed.

### 3. Agent Output Is Untrusted

Agent-produced code is isolated until validated and promoted. The system assumes agents may produce broken, redundant, or conflicting work.

**Implication:** Validation gates, file locking, code freezing, and candidate groups exist to enforce quality and prevent cross-agent interference.

### 4. Append-Only History, Explicit Rewrites

Commits are immutable. History is append-only. Rewriting (`undo`, `rebase`, `split`) is an explicit, logged operation — never silent.

**Implication:** `undo` pushes to a redo stack. `rebase` creates new commits rather than mutating old ones. The operation log (`ops.json`) records every structural change.

### 5. Content-Addressable Storage

Objects (blobs, trees, commits) are keyed by SHA-1 of their canonical representation. This is the same hashing scheme as Git, enabling a future one-way bridge (`codetree export` to Git).

**Implication:** Deduplication is automatic. Object integrity is verifiable. No dependency on Git libraries.

### 6. No Git Dependency

CodeTree is a complete VCS. It does not shell out to `git` or link against `libgit2`. All operations (commit, merge, diff, rebase, checkout) are implemented natively in Rust.

**Implication:** Smaller dependency tree. No subprocess overhead. Full control over semantics. The trade-off is that CodeTree must implement its own merge algorithm, diff engine, and rebase logic.

### 7. Agent-First API

Core CLI commands have an MCP twin that returns typed JSON. Agents drive CodeTree via JSON-RPC, never shell parsing.

**Implication:** The MCP layer operates at the same level as the CLI command layer — both call the `VcsManager`/`BranchManager` primitives. Output is structured, not text-scraped. A few CLI commands (`redo`, `split`, `smartlog`, `switch`/`next`/`prev`, `watch`, `resolve`, `worktree`, `agents`) do not yet have MCP twins — see `TODO.md`.

---

## Architecture Decisions

### ADR-1: Native VCS vs. Git Wrapper

**Decision:** Build a native VCS engine instead of wrapping Git.

**Rationale:** A Git wrapper would bolt agent concepts (ownership, locking, lifecycle, gates) on top as metadata. CodeTree makes them first-class in the data model. Ownership and locking live in the store, enforced at commit time. Rollback is a structured object-graph operation, not a fragile `git reset`. The operation lifecycle is part of history.

**Trade-off:** CodeTree must implement its own object store, merge algorithm, diff engine, and rebase logic. This is significant complexity, but it gives full control over semantics and eliminates the `git2` dependency.

### ADR-2: SHA-1 Object Hashing (Git-Compatible)

**Decision:** Use the same SHA-1 content-addressing scheme as Git (`"<type> <len>\0<content>"`).

**Rationale:** A future `codetree export` can map objects directly to a Git repository without re-hashing. Objects are stored in the same fan-out layout (`objects/<first-2-hex>/<remaining-38-hex>`).

**Trade-off:** SHA-1 has known collision weaknesses. For an AI-agent VCS with local-first operation, this is acceptable. A future version could migrate to SHA-256.

### ADR-3: File-Based State (No Daemon)

**Decision:** All state lives in `.codetree/` as files. No daemon, no service, no database.

**Rationale:** Offline-first. Works on any filesystem. No port conflicts. Simple backup (copy `.codetree/`). The trade-off is no concurrent multi-process writes — but agents typically interact through the MCP server, which is a single process.

### ADR-4: Operation Log for Undo/Redo

**Decision:** Maintain an explicit operation log (`ops.json`) with a redo stack, rather than using `git reflog` or similar.

**Rationale:** The log records structural operations (`Start`, `Save`, `Merge`, `Withdraw`) — not low-level ref changes. This makes undo/redo semantically meaningful: "undo the start of this operation" rather than "undo the last ref update."

### ADR-5: File Locking at Operation Level

**Decision:** Locks are per-file, per-operation. An operation claims files at `start` time; other operations cannot modify them until the owner finishes or withdraws.

**Rationale:** Prevents merge conflicts by design. Agents working on the same file are forced into a queue. The trade-off is reduced parallelism when files overlap — but this is the desired behavior for AI agents that would otherwise produce conflicting work.

### ADR-6: Candidate Groups for Solution Selection

**Decision:** Model multiple solutions to the same problem as a **candidate group** — a named set of operations. `promote` merges the winner and withdraws the rest.

**Rationale:** Agents may produce different solutions with different trade-offs. Rather than merging blindly or requiring human arbitration, CodeTree stores all candidates, allows evaluation, and promotes the best one. The losers are cleanly withdrawn.

### ADR-7: MCP as First-Class Interface

**Decision:** The MCP server is a first-class interface operating at the same layer as the CLI commands. It calls the same `VcsManager`/`BranchManager` primitives that `commands::*` uses.

**Rationale:** Agents should not parse CLI text. The MCP interface provides typed JSON for core operations. Caveat: the MCP layer currently re-implements some orchestration rather than calling `commands::*` directly, so CLI and MCP behavior can drift (e.g. MCP `start_op` lacks `--wait`). Consolidating on shared command functions is future work, as is adding MCP twins for the remaining CLI commands (`redo`, `split`, `smartlog`, `switch`/`next`/`prev`, `watch`, `resolve`, `worktree`, `agents`).

---

## Data Model Design

### Object Store

```
Blob   → { content: Vec<u8> }                     → SHA-1
Tree   → { entries: Vec<(mode, name, blob_hash)> } → SHA-1
Commit → { tree_hash, parents: Vec<hash>, author, message, timestamp } → SHA-1
```

Objects are immutable. Writing the same content always produces the same hash and is a no-op if the object already exists.

### Refs

```
refs/heads/<branch-name> → commit hash
HEAD                     → symbolic ref to branch name
```

Refs are mutable pointers. `HEAD` is a symbolic ref — it always points to a branch, never directly to a commit.

### Operation Metadata (branches.json)

```
BranchInfo {
    name: String
    created_at: u64
    updated_at: u64
    change_group: { description, files: Vec<String> }
    status: Active | Merged | Archived
    template: Option<String>
    worktree: Option<PathBuf>
    branchless: bool
    depends_on: Vec<String>
    last_commit: Option<String>
    tags: Vec<String>
    parent_branch: Option<String>
    agent_id: Option<String>
}
```

This is the operation-centric metadata layer. It tracks what the operation is, who owns it, what files it touches, what it depends on, and its lifecycle status.

### Operation Log (ops.json)

```
Operation ::= Start { branch, timestamp, agent_id }
            | Save  { branch, message, timestamp }
            | Merge { branch, into, timestamp }
            | Withdraw { branch, timestamp }

ops: Vec<Operation>       // undo history
redo_stack: Vec<Operation> // redo history
```

### Supporting State

| File | Purpose |
|---|---|
| `locks.json` | File locks: `path → operation_name` |
| `frozen.json` | Frozen paths: read-only protection |
| `candidates.json` | Candidate groups: `group_name → [operation_names]` |
| `resolutions.json` | Conflict resolution cache: `(path, our_blob, their_blob) → resolved_blob` |
| `pending_resolution.json` | Active merge conflict metadata for `resolve` command |
| `config.toml` | User configuration (base branch, templates, validation, hooks) |

---

## Module Design

### Layering

```
┌─────────────────────────────────────────────┐
│  CLI (main.rs)    MCP (mcp.rs)              │  Entry points
├─────────────────────────────────────────────┤
│  commands/                                    │  Command logic
│  ├── mod.rs (shared utils + re-exports)      │
│  ├── init.rs, operations.rs, save.rs         │
│  ├── merge.rs, finish.rs, status.rs          │
│  ├── undo.rs, rebase.rs, compare.rs          │
│  ├── worktree.rs, freeze.rs, lock.rs         │
│  └── agents.rs                               │
├─────────────────────────────────────────────┤
│  branch.rs   ops.rs   config.rs              │  Metadata layer
│  lock.rs     freeze.rs  candidates.rs        │
│  resolution.rs                               │
├─────────────────────────────────────────────┤
│  vcs/                                        │  VCS engine
│  ├── objects.rs  refs.rs  index.rs           │
│  ├── repo.rs     manager.rs (core)           │
│  ├── merge.rs    rewrite.rs                  │
│  └── query.rs    worktree.rs                 │
├─────────────────────────────────────────────┤
│  error.rs   lib.rs (utils)                   │  Foundation
└─────────────────────────────────────────────┘
```

### Module Boundaries

- **`vcs/`** — Pure VCS primitives. No knowledge of operations, agents, or locking. Knows about blobs, trees, commits, refs, and the index.
- **`branch.rs`** — Operation metadata. Knows about operations, their status, tags, dependencies, and parent relationships. Does not know about VCS internals.
- **`commands/`** — Orchestration layer. Calls `vcs/` for storage operations and `branch.rs` for metadata. Enforces policies (locking, freezing, validation).
- **`mcp.rs`** — MCP protocol layer. Calls `commands::*` directly. Translates between JSON-RPC and Rust types.
- **`lock.rs`, `freeze.rs`, `candidates.rs`** — Policy modules. Independent of each other and of `vcs/`. Enforced by the command layer.

### Command Module Split

The original `commands.rs` (2,692 lines) is split into 14 focused modules under `commands/`:

| Module | Responsibility |
|---|---|
| `mod.rs` | Shared utilities (`load_config`, `run_hooks`, `staleness_label`, `format_ts`, `withdraw_single`) + `pub use` re-exports |
| `init.rs` | Repository initialization |
| `operations.rs` | Operation creation (`start`), navigation (`switch`, `next`, `prev`) |
| `save.rs` | Committing changes (`save`, `split`, `watch`) |
| `merge.rs` | Merging (`merge`, `resolve`) |
| `finish.rs` | Lifecycle completion (`finish`, `withdraw`) |
| `status.rs` | Inspection (`status`, `list`, `smartlog`, `whereami`) |
| `undo.rs` | History correction (`undo`, `redo`) |
| `rebase.rs` | Branch maintenance (`rebase`, `restack`) |
| `compare.rs` | Comparison and publishing (`compare`, `publish`) |
| `worktree.rs` | Linked worktree management |
| `freeze.rs` | Code freezing (`freeze`, `unfreeze`, `frozen`) |
| `lock.rs` | Lock management (`unlock`, `locks`) |
| `agents.rs` | Agent tracking and candidates (`agents`, `evaluate`, `promote`) |

All modules use `pub use` re-exports from `mod.rs`, so `crate::commands::*` and `codetree::commands::*` paths remain unchanged.

---

## Design Rationale

### Why Parallel by Default?

Human VCS workflows assume a single developer at a keyboard who switches branches to work. AI agents are spawned by orchestrators that may create 10 operations in parallel. If `start` checked out the new branch by default, the orchestrator's working tree would thrash. Parallel-by-default means `start` creates the branch ref and returns; the agent (or orchestrator) decides when to switch.

### Why File Locking Instead of Merge Conflict Resolution?

Merge conflicts require human arbitration in traditional VCS. AI agents cannot reliably resolve conflicts — they may pick the wrong side or produce broken merges. File locking prevents conflicts by design: if agent A is working on `auth.rs`, agent B cannot touch it. B either waits (`--wait` flag) or works on a different file. This trades parallelism for correctness.

### Why a Native VCS Instead of Git Metadata?

Adding agent concepts as a metadata layer on top of Git would mean:
- Locking is advisory (Git doesn't enforce it).
- Rollback is `git reset` (fragile, loses history).
- The operation lifecycle is external to the VCS (inconsistent state on crash).
- MCP tools would parse `git` CLI output (brittle).

A native VCS makes locking, freezing, validation, and lifecycle **enforced at the storage layer**. The trade-off is implementation complexity — but the result is a coherent system where the data model matches the product model.

### Why Not Use a Database?

CodeTree is offline-first and single-process (the MCP server). A database would add a dependency, require a daemon, and complicate backup. File-based state (JSON + content-addressable objects) is simpler, portable, and sufficient for the workload.

### Why SHA-1 Instead of SHA-256?

Git compatibility. A future `codetree export` can map objects directly to a Git repository. SHA-1's collision weakness is not a security concern for local-first operation. A migration to SHA-256 is possible in the future.

---

## Future Design Directions

- **Remote protocol** — Push/pull/clone for agent-to-agent and agent-to-human collaboration.
- **Git interop** — One-way bridge: `codetree import` from Git, `codetree export` to Git.
- **First-class conflicts** — Store conflict metadata in commits (like Jujutsu) instead of aborting.
- **Auto-snapshot** — Snapshot the working copy before every command, so agent crashes never lose work.
- **JSON output mode** — `--json` flag on every CLI command for machine-readable output without MCP.