Keeper is the object-store dog: its purview is git object storage, and it owns those objects — append-only NNNNN.keeper pack logs, their NNNNN.keeper.idx kv64 indexes, and a project refs reflog, one flat shard per project. The goal is a store trivially git-exchangeable yet never rewriting packs, so packs copy verbatim and a dropped branch costs only a refs tombstone. The method: address by 60-bit hashlets, append to pack logs, index as sorted kv64 runs, resolve deltas within the single project pool.
hashlet60|type4 keys, so a hash-prefix lookup is one range query spanning all object types.refs tombstone, not a dir delete: objects linger in the shard until an epoch recompaction.refs reflog; a branch's refs is authoritative — resolution does not walk up.Keeper follows the Dog three-call contract plus an incremental pack writer; objects are read by hashlet or URI and written through the pack API.
KEEPOpen / KEEPOpenBranch / KEEPClose — open the store, select a branch's tips within the one shard, then close it.KEEPExec(state, cli) — run a parsed verb plus URIs against the open store.KEEPGet / KEEPGetByURI — read an object by hashlet or by a full URI into a buffer.KEEPLookup — range-query the kv64 index across the project pool, returning (file_id, offset) for the first hit.KEEPHas / KEEPGetSize — existence and size probes by hashlet.KEEPPackOpen / KEEPPackFeed / KEEPPackClose — incremental pack writer; Feed appends one object and returns its sha.KEEPResolveRef / KEEPResolveHex — resolve a ?ref or a hex prefix to a full sha.KEEPIsAncestor — ancestry test backing the ff-only push and advance checks.
The keeper CLI clones, fetches, resolves, and cats by URI, plus a few maintenance verbs; be normally drives it rather than the user.
keeper get //host/path clones, //host?tags/v6.0 fetches a ref, .?heads/master resolves, .#abc1234 cats an object.keeper refs lists refs, keeper import pack ingests a git packfile, keeper status shows store stats.keeper verify .#sha checks a commit and all reachable objects; keeper alias //name url records a host alias.Pack logs are append-only, git-encoded object files — close to git's packfile format but not valid git packfiles, with no trailing checksum; see PackLog for the full format.
git-upload-pack; later fetches and KEEPPackFeed append objects.FILEBook, read via FILEMapRO.Each index entry is 16 bytes — a u64 key and u64 val — sorted by hashlet then type, so a hash-prefix lookup is one range query over all types; see Indices for the shared sorted-run format.
key = hashlet60 | obj_type4 (commit/tree/blob/tag in the low 4 bits); val = offset40 | file_id20 | flags4, wh64 layout.file_id is the store-wide NNNNN of the pack log; it resolves to a file in the single project shard, no per-dir search.All of a project's objects share one flat pool; a REF_DELTA may delta against any earlier object in that pool, with no cross-project base, which keeps each shard self-contained.
refs tombstone: objects linger in the shard; GC is an out-of-band epoch recompaction, not a delete.(file_id, offset), chase the delta chain bottom-up — no walk-up.
The project <project>/refs is an append-only reflog (a dog/ULOG) holding every branch, tag, and host alias as rows; the verb is always set and the key/val pair is packed into one URI.
<ron60-ms>\tset\t<from-uri>#?<40-hex-sha>; REFSLoad splits on # to return {key,val}, ts monotonic.?heads/main#?<sha>); remote-tracking a full origin (//origin/path?heads/feat#?<sha>).//github#?https://…); a branch's refs is authoritative, no walk-up.