AVCS

AVCS — Agentic Version Control System

*An AI-native version control system for humans and AI agents working concurrently.*

An agent should not spend its context on version control. That is the whole design goal, and it is measured rather than asserted — here is what the same work costs an agent:

git's recovery cost tracks the size of the file — a conflict is bytes inside it, so the agent reads the whole module and writes the whole module back to change one line. AVCS's tracks the size of the change: a conflict is an object naming the two contending operations, so it stays flat as the file grows. There is also no branch to rewrite and nothing to force-push, which is why the round trips differ — and that is *one* cycle, repeated for every PR that merges ahead of yours. Across the file sizes measured the saving is 37–99%.

None of this is a compression trick bolted on afterwards. It falls out of storing the operation graph instead of snapshots: there is no rebase to perform, so there is nothing to re-read. Method, caveats and the harness that produced the rebase numbers: avcs-demo → what it costs an agent in tokens. The schema figures are the advertised MCP surface itself — 35 KB of JSON against 14 KB, at the usual ≈4 bytes per token.

Git records when the code changed.

AVCS records who changed it, with what intent, on what evidence, and through which conflict decisions the code reached its current state.

AVCS is a new, deliberately Git-incompatible version control system built for a world where humans and many AI agents edit the same codebase concurrently. It drops the commit / branch / merge / conflict-marker model and instead stores intent, session, operation, evidence, and decision as first-class objects. The code tree is not the source of truth — it is a projection computed by deterministically *reducing* the operation graph:

state = reduce(base, operationDAG, decisions, policy, materializer)

The same objects + the same policy + the same materializer produce the same tree on any replica. Merging is not text selection; it is a pure, deterministic reduction.

Status: research prototype. The implementation is real and test-covered, but every phase is built to a *working-MVP depth* (language-neutral text 3-way merge, ed25519 signing). Structure-aware merge, semantic-break detection, multi-signature trust, and hardened distributed sync are tracked on the roadmap.

Jump in: install · your first five minutes · work against a server · connect an agent over MCP · agent quickstart walkthrough

See it run first: izagood/avcs-demo — a runnable demo of the question this design answers: *what happens when two agents edit the same file at the same time?* One ./demo.sh walks a stale-head land that is absorbed instead of rejected, a same-file auto-merge with no rebase, and a same-line collision that becomes a signed decision rather than conflict markers.

Why not a layer on top of git?

Every "AI + git" tool eventually stores the agent's context *beside* the history — commit trailers, PR comments, sidecar JSON. AVCS exists because these objects have to be load-bearing — consumed by the merge machinery itself — and bolted onto git they can't be:

• Evidence must gate merging. git happily merges a behavior change with no passing test. In AVCS that change is graded L3 — blocked by the reducer until *trusted* evidence lands, and an operation's own author vouching for it does not count.
• Decisions must outlive the merge. git merge resolves a conflict by emitting bytes; the choice and its rationale evaporate. An AVCS decision is a signed object — recallable later, and prior decisions bias future auto-resolution.
• Concurrent edits must not degrade into conflict markers. Two agents editing one file meet a deterministic policy reduction (L0–L4 below), not <<<<<<< in the tree plus a human holding the pieces.
• Intent must travel with the work. A trailer is inert text. An intent (goal + constraints + allowed scope) is what sessions open against, what leases and contention checks are scoped by, and what avcs.context.build hands the next agent.

git stores snapshots and leaves the merge to text selection; AVCS stores the operation graph and makes the merge a computation over intent, evidence, and decisions. That is why it is deliberately git-incompatible — these objects are the engine, not metadata. (git interop still exists, as a bridge: docs/14, docs/20.)

Core principles

How it works

Every meaningful thing is a content-addressed, append-only object. Code is a *projection* over the operation DAG, never stored as commits.

…plus blob for raw content and the governance objects (lease, membership, protection, promotion, redaction, override, approval, line, integration) used by the multi-machine and security phases.

Conflict resolution levels

AVCS never falls back to last-write-wins for code. Contending operations are graded and resolved with a recorded rationale:

• L0 / L1 — different entities, or disjoint line regions in the same file → auto-merge
• L2 — concurrent edits that overlap the same line region → policy auto-decision (human-preferred, trust-weighted); the auto-decision is itself recorded in autoDecisions
• L3 — a behavior change with no *trusted* evidence → blocked
• L4 — a public-API break → requires a human decision, routed to the scope's owners

Evidence trust matters: an operation's own author cannot vouch for it. Evidence-gating and the passing-test bonus only count evidence produced by a *non-authoring, trusted* actor (CI bot / human).

What works today

The reducer and policy engine are the foundation; the higher phases build distributed collaboration, security, and observability on top.

Foundation (Phases 1–6)

• Storage core — append-only, content-addressed object store (.avcs/objects)
• Deterministic reducer + policy engine — the L0–L4 conflict grading above, with a priority ladder, bounded reliability nudges, and auditable auto-decisions
• Language-neutral text merge (Phase 2) — a deterministic N-way line-level 3-way merge (src/merge/merge3.ts), so edits to disjoint regions of one file auto-merge regardless of language; overlapping edits become a policy-resolved conflict region. No language parsing in the core
• Cryptographic trust (Phase 3) — ed25519-signed evidence/decision; forged signatures fail the trust gate. Real validation runner, WorkLease, RepairContext
• Decision memory (Phase 4) — recallable prior human decisions (recallDecisions) and distilled "learned policies" that bias future auto-resolution
• Policy depth (Phase 5) — code-owner routing and bounded reliability learning
• Release & provenance (Phase 6) — verified checkpoints + CycloneDX SBOM + signed artifacts

Collaboration, scale & security (Phases 7–12)

• Phase 7 — multi-machine: membership/roles (signed key federation), pull (object gossip; two replicas converge to the same treeHash), protection + finalize CAS (non-fast-forward rejected, so a stale push can't overwrite fresh history)
• Phase 8 — lineage: long-lived divergent lines (e.g. v1.x ∥ v2.x, same path, different content, zero conflict), portOp (backport = cherry-pick)
• Phase 9 — scale: entity index, materializeAt (time travel), chunked large-blob storage with dedup
• Phase 10 — observability: blame (who/why), logP, deterministic bisect, diff
• Phase 11 — external contributions: quarantine tier + promote + untrusted-CI gate
• Phase 12 — security: redact (byte-eviction of leaked secrets, oid preserved), break-glass override, forward-only rollback
• Local undo (docs/23) — avcs undo [--last | …] [--purge] [--no-git]: drop local ops from the view, and with --purge evict the bytes they uniquely reference. Refuses once the ops have been pushed, because that case belongs to admin-gated redact. In a git-bridged repo --purge clears the git copy too — but only where it can prove the rewrite is safe and local (nothing on a remote, the commits at the tip, no other work in them, a clean tree); anywhere else it still does the AVCS side and names precisely what is left and the one command that fits, up to and including "rotate the credential, it is already published"
• The working tree is genuinely derived — checkout records what it projected (.avcs/projection.json, path → blob oid) and, on the next projection, removes the files the target view no longer contains. Files it never wrote — build output, ignored files, anything you just created — are untouched, and a projected file you have since edited is kept and named in a notice rather than silently overwritten. Switching views therefore yields *that view*, not the union of every view pro