Module merge 

Merge — replaying a branch into a destination as NEW history.

A merge does not graft

The tempting implementation is to take the branch’s nodes and attach them to the destination’s chains. It is also wrong here, and for a structural reason rather than a stylistic one: those nodes were written at the branch’s sequences, against the branch’s predecessors, and hashed over that content. Making them part of the destination means either rewriting them (which changes their hashes, so they are not the nodes any more, and any root that committed to them is now false) or admitting into the destination a version chain whose sequences do not belong to the destination’s sequence space. Both break the constitutional rule that committed history is immutable.

So a merge COMPUTES what the branch changed and REPLAYS it as fresh writes at the destination tip. The branch’s own nodes stay exactly where they were, still valid, still hashed over what they always were. The destination gains new versions, with new sequences, on top of the ones it already had. Nobody has to lie.

The visible consequence — and the test that proves it — is that the destination’s pre-merge value remains readable with AS OF. A merge adds history; it never replaces it.

Three-way, with the convergent case called out

For each document the branch touched, three values are compared: BASE (the destination as of the fork point), OURS (the destination now) and THEIRS (the branch). Unchanged on one side means take the other. Changed on both to different values is a conflict.

Changed on both to the SAME value is NOT a conflict. Two people independently making a document say the same thing have not disagreed about anything — there is no decision for a human to make, and no information to be lost by proceeding. Reporting it would be reporting the coincidence of agreement as a failure, and in practice (a schema default applied on both sides, a backfill run twice) it is the single most common way a merge gets blocked for no reason. It contributes no replay either: the destination already holds the value.

Structs

MergePlan

What a merge would do. Produced by plan, consumed by execute.

MergeRecord

The durable record that a merge happened.

PlannedChange

One document the merge would write, and the evidence for writing it.

Enums

ChangeKind

What a replayed change does to the destination.

Constants

MERGES

The merge log. Ids are the zero-padded destination sequence the merge landed at, so lexicographic order is chronological order.

Functions

execute

Carry out a plan: replay its changes into the destination, record the merge, and close the branch.

get_merge

A merge record by the sequence it landed at.

list_merges

Every merge, oldest first.

plan

Work out what merging branch would do. Writes nothing.