Hop/wiki/Architecture.md

Architecture

Hop uses Git under the hood, but it is not merely a directory of metadata files inside .git.

Git responsibilities

Git provides:

• content-addressed blobs and trees;
• synthetic commits for immutable snapshots;
• detached worktrees for attempt isolation;
• three-way merge behavior;
• diffs and path inspection; and
• interoperability with existing repositories.

Hop never needs to move the user's active branch or rewrite the real index. Private objects are pinned beneath refs/hop/states/*; accepted history is mirrored at refs/hop/accepted.

Hop responsibilities

.hop/hop.db is a SQLite WAL database containing:

• prompt/task/attempt identity;
• typed state edges and accepted lineage;
• evidence tied to exact source trees;
• session heads for Desktop follow-ups;
• materialized-root state; and
• immutable audit events.

Project layout

.hop/
├── hop.db
├── workspaces/
├── checks/
├── integration/
└── *.lock

.hop/ is added to .git/info/exclude, not the public .gitignore. Hop refuses initialization when .hop is already tracked as user-owned project content.

Acceptance consistency

Acceptance is serialized and compare-and-swapped. SQLite is authoritative; derived Git refs can be repaired by hop doctor --repair. Desktop landing also tracks which accepted state is physically visible, allowing safe catch-up with hop sync without treating a divergent folder as disposable.

For the full product direction, read the product blueprint.