Module branch 

Branching — a line of history that forked from a known sequence.

The shape that was chosen, and the one that was rejected

A branch here is a CHILD STORE WITH READ-THROUGH: it has its own write space, and a read that the branch has not written falls through to the parent as the parent looked at the fork point.

The rejected alternative was divergent refs inside one global sequence space — two heads, one monotonic counter, order decided by whoever wrote last. That cannot be made honest. A single monotonic sequence is a total order, and two concurrent lines of history are not totally ordered. Encoding them in one counter forces the engine to assert an ordering between writes that have no ordering, and every AS OF afterwards reports that invention as a fact. Better to have two sequence spaces and admit they are two.

What is actually built here (Phase 5A) versus what is coming (5B)

crate::store::ObjectStore is a concrete struct wired directly into crate::db::Db, not a trait, so a genuinely separate child store is a large surgery on the substrate. Until that lands, the child store is modelled as an OVERLAY: branch writes go to the reserved BRANCH_WRITES collection in the parent store, tagged with the branch they belong to, and branch_get implements the read-through against get_as_of(base_seq).

The overlay is not a fake. The three-way merge, the conflict detection, the pinning and the merge records all run against real recorded branch writes with real isolation from the destination: a branch_put is invisible to db.get on the user collection, and db.put on the destination is invisible to branch_get. What the overlay does NOT give is an independent sequence space — see the PHASE 5B: notes below for exactly what changes.

Pinning

A live branch will one day need to reconcile against its fork point. If compaction discards the history at base_seq, that reconciliation becomes impossible and the branch becomes a promise the engine cannot keep. So a live branch PINS its base, and compact refuses rather than stranding it.

Structs

BranchRecord

A forked line of history.

BranchWrite

A single write made on a branch, as recorded in the overlay.

Enums

BranchStatus

Where a branch is in its life.

Constants

BRANCHES

The branch registry. One record per branch GENERATION (see branch_key).

BRANCH_WRITES

The branch write overlay — the child store, until the store actually splits.

Functions

abandon_branch

Retire a branch without merging it. Returns false when there was no live branch by that name to abandon.

branch_delete

Delete a document on a branch.

branch_get

Read a document as the branch sees it: the branch’s own write if it has one, otherwise the PARENT AS OF THE FORK POINT.

branch_key

The registry id for one generation of a branch name.

branch_put

Write a document on a branch. Invisible to the destination until merge.

branch_writes

Every write a branch has made, sorted by (coll, id) so a plan is deterministic run to run.

create_branch

Fork a branch from base_seq.

get_branch

The current branch answering to this name.

list_all_branches

Every branch generation ever recorded, oldest first.

list_branches

Every ACTIVE branch, sorted by name.

minimum_pinned_seq

The oldest sequence any LIVE branch still needs. None when nothing is pinned, which is the only state in which history may be discarded freely.

pinning_branches

Every live branch and the sequence it pins, sorted by name.

validate_branch_name

Is this a name a branch can durably have?