Why hav exists

hav re-derives version control from how software is written now: by humans and agents working in parallel, at machine speed, on work that sometimes must stay private until a chosen moment. This page explains the diagnosis behind that design. It has no commands and no examples, only the argument.

One hash, three jobs

Git's deepest design decision is that a commit hash commits to everything at once: the content of every file, the identity of every ancestor, the author, the date, the message. That single recursive hash is git's integrity structure and its history structure. It is also its disclosure structure, because you must reveal bytes to verify them.

That conflation is elegant, and it causes almost every well-known git problem. hav names the three jobs and gives each its own plane:

A snap is parentless: no author, no date, no message, no parents inside the hash. All story lives in the narrative plane, attached to knots whose identity stays stable as their content evolves. Secrecy is key distribution layered on top, touching neither. Once the planes are separate, each of the four problems below has an obvious fix.

The four founding problems

P1: You can't have private work inside a shared repo

In git, the integrity structure is the disclosure structure: one recursive hash commits to all plaintext, so you must reveal everything to verify anything. This has visible consequences:

• Patch gapping is an industry. Chrome/V8 fixes have reached exploit brokers' subscribers within days of appearing on public code review, weeks before reaching stable users. Roughly half of analyzed in-the-wild 0-days have been variants of already-patched bugs. The gap between "fix visible" and "fix deployed" is the attack surface.
• The workarounds are broken. GitHub Security Advisory private forks run no CI. Coordinated-disclosure mailing lists are human-tracked and leak.
• It has been done before. Google's internal monorepo is default-open with file-level ACLs on a sliver of the tree, every read audited, and purge-from-history a supported operation. Private work inside a shared repo requires only that the disclosure plane be separate.

hav's answer: sealed crews (client-side encryption at buoy granularity), with reveal as an ordinary history operation that changes no ids. The key is the disclosure plane. Ciphertext travels to everyone, and only members open it. Per-person wire enforcement and who-saw audit belong to the hosting layer above.

P2: Committing is ceremony, and editing history is dangerous

In git, facts and story are one object. Editing the story (rebase, squash, reorder) renumbers the facts, so every downstream pointer breaks and the tooling piles on warnings. The result is the add/commit/stash/amend dance and a culture that fears history curation.

hav's answer: the working copy is the unit of work, captured automatically. There is no staging area, no stash, no "uncommitted changes" limbo. Identity (the knot) is separate from content (the snap), so describing, splitting, squashing, and absorbing are cheap narrative edits. Rewriting a knot automatically rebases its descendants, which is safe because conflicts are data and nothing ever blocks. You curate history after the work instead of getting it right in the moment.

P3: Checkouts take branches hostage

Git entangles "where my files are" with "a mutable ref": a branch can be checked out in only one place, worktrees share mutable metadata, and one subagent's checkout can move another's HEAD. Fleets of coding agents turn this into an active hazard. A cottage industry exists just to arbitrate git worktrees between agents.

hav's answer: a workspace is a database row {knot, base buoy, snap}. Any number of workspaces can track the same buoy, each with its own knot, and "already checked out elsewhere" is inexpressible. Nothing moves a workspace's files uninvited, because a build or an agent might be running against that tree.

P4: The store is a pile of files behind no API

Git's object store is a directory format, the working copy is load-bearing, and every operation goes through the filesystem. Filesystems are the wrong substrate for a transactional store: they make multi-object atomicity impossible and put every tool at the mercy of platform quirks.

hav's answer: one SQLite file per repo. Every mutating command is a single transaction with a full before/after view, which is also what makes perfect undo possible. Push and pull are one process copying rows between two databases, and the harbor is a thin HTTP layer over the same store.

Why not fix git?

Because the fixes sit at the bottom of the design. Jujutsu proved the working-copy-as-commit model in the wild, and its residual pain shows how much tax git compatibility charges: checkout state smuggled into bookmarks, stable ids in sidecar tables, divergence every time a GitHub round-trip rewrites history. A disclosure plane cannot be retrofitted at all, because git's hash is its disclosure structure.

hav is standalone by design. There is no git bridge in or out: the way in is files, and the way out is files. That costs adoption, since every editor integration, CI system, and forge assumes git. The bet is explicit: for agent-driven, greenfield, or privacy-sensitive work, the model is worth more than the ecosystem.

Non-goals

• No git interoperation. hav never uses, shells out to, or reads git.
• No workflow engine. hav records facts and story. Scheduling agents, assigning reviews, and orchestrating sandboxes belong to the layers above.
• No hosted service. Remotes are paths or URLs of harbors you run. A GitHub-equivalent site can be built on top, but it will never be baked in.
• No trustless claims. Where a guarantee would need a trusted party or an audit trail, hav says so and leaves the job to the hosting layer rather than hiding it behind cryptographic theater. See Design principles.