Repository navigation
docs(adr): propose ADR-0049 merge on partial clones (P37c) - #181
Conversation
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…rsecting enumeration, wrap union, pull-based engine, clean merges first) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ions, state merge ordering Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configuration
📒 Files selected for processing: 3
✨ Finishing Touches
Comment |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dfa0b75249
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| and fills (lazy) or refuses (otherwise) only the region where all three sides | ||
| differ. Clean merges first, then conflicts, then cherry-pick/rebase; sessions |
There was a problem hiding this comment.
Include policy and view regions in the fill summary
The roadmap's “only” claim contradicts ADR-0049 itself: decision 3 requires enumerating and therefore fetching policy-intersecting subtrees even when, for example, base == ours, and decision 5 additionally fetches the sparse view closure regardless of whether those paths differ. This understates the network and non-lazy refusal behavior in the phase summary; describe the scope as the differing region, rule-intersecting region, and view closure.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed: the ROADMAP summary now says the fill/refusal scope is the differing region, the rule-intersecting region, and the sparse view's closure, matching decisions 3 and 5.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0951e3e0e7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### 5. The engine is pull-based; filling happens outside the store lock | ||
|
|
||
| `Filler` takes the store mutex (`fill.rs:283`), and the current merge engine runs while holding it (`repo.rs:1362`). A callback from inside the merge would deadlock. Instead `merge_trees` returns either a finished `TreeMerge` or `Needs(ids)`: the subtrees it must read and does not hold. The caller drops the lock, fills those ids (lazy and online) or fails with `GapInView` naming the path and the `sc backfill` prefix (otherwise), and calls again. Each round is idempotent, and progress is by presence. |
There was a problem hiding this comment.
Preserve paths when returning missing IDs
When a non-lazy or offline merge encounters an absent differing subtree, Needs(ids) discards the traversal path that the next sentence requires for GapInView. An object ID does not identify a unique path because subtrees can be aliased, and an absent root has no path recoverable from local tree data, so the caller cannot reliably name the promised sc backfill <prefix> repair. Return the discovered path with each missing ID, or have the engine construct the refusal while it still has that context.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed: Needs now returns (ObjectId, path) pairs, so the refusal can name the path and the sc backfill prefix even when subtrees alias; an absent root is reported as the empty path.
…iew refusal Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b9573b2196
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### 5. The engine is pull-based; filling happens outside the store lock | ||
|
|
||
| `Filler` takes the store mutex (`fill.rs:283`), and the current merge engine runs while holding it (`repo.rs:1362`). A callback from inside the merge would deadlock. Instead `merge_trees` returns either a finished `TreeMerge` or `Needs(missing)`, where each entry is `(ObjectId, path)`: the subtree it must read and does not hold, with the path at which the traversal found it (an id alone does not identify a path, since subtrees alias, and an absent root has no path to recover from tree data; the root is reported as the empty path). The caller drops the lock, fills those ids (lazy and online) or fails with `GapInView` using the first reported path and its filter prefix (otherwise), and calls again. Each round is idempotent, and progress is by presence. |
There was a problem hiding this comment.
Return missing blobs from the pull loop
When an enumerated differing or policy-intersecting region contains a blob omitted by the partial clone—which is routine outside its filter—the promised MergedFile result still requires that blob's bytes, and encryption occurs before the later ensure_view. Restricting Needs to missing subtrees therefore leaves the leaf read to fail with NotFound, so the lazy merge cannot handle the documented out-of-view differing-region case. Include missing blob IDs and their paths in the pull protocol, not only subtrees.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed: Needs now returns missing blobs as well as subtrees, since the leaf merge and encryption read blob bytes; they fill through the same batched by-id path.
| So 37c-i separates the dimensions, in **both** engines: | ||
|
|
||
| - **Content** resolves exactly as today: by blob id (and the `PROTECTED` bit for protected paths). Nothing about content resolution, diff3, sealing or wraps changes. | ||
| - **Mode** is merged afterwards, independently, as a three-way on the modes of the entries that exist: equal on both sides, take it; one side equal to base, take the other's; both sides changed differently, executable if either is (today's rule for that case, kept as the tiebreak). Example: base `(X,0755)`, ours `(X,0644)`, theirs `(Y,0755)` resolves content to Y (ours is unchanged from base by id, so theirs wins) and mode to `0644` (ours changed it, theirs did not), so ours' executable removal is kept. |
There was a problem hiding this comment.
Preserve the survivor's mode on delete/modify conflicts
The independent mode three-way has no valid result when one side deletes an entry while the other changes its content but retains the base mode. For example, base (X,0644), ours absent, and theirs (Y,0644) is a delete/modify conflict whose content logic keeps theirs, but the stated mode rule sees theirs equal to base and selects ours' nonexistent mode. This affects the full-clone engine as soon as decision 1 lands; explicitly use the surviving entry's mode when content resolution retains a file from a delete/modify conflict.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed: the mode three-way only votes between entries that are both present; for a delete/modify conflict the result takes the surviving entry's mode.
|
|
||
| ### 6. The result keeps plaintext out of the CAS | ||
|
|
||
| `TreeMerge` is not a bare tree id. It returns what `FileMerge` returns today (the enumerated `MergedFile` list with `needs_encrypt` plaintext, sidecars, conflicts, `wrapped_carry`) **plus** the carried subtrees as `(path, TreeEntry)` pairs. The existing pipeline (`repo.rs:1385-1530`) handles the enumerated files unchanged (routing through union rules, encryption, plaintext never written to the CAS). The carried entries are overlaid by id when the final tree is assembled: a recursive overlay rebuilds each ancestor directory from the enumerated files at that level, inserts the carried entries verbatim (id, mode, perms untouched), and keeps the enumerated siblings, with the collision check above run over the combined names. No new code path touches plaintext. |
There was a problem hiding this comment.
Add an explicit representation for a carried root
A real non-fast-forward merge can shortcut at the root itself—for example, two branches that make disjoint secret-registry changes have identical base/ours/theirs root IDs, or a secrets-only commit can merge with a file-changing sibling while base_root == ours_root. Snapshot roots have no enclosing TreeEntry or ancestor directory, so the described (path, TreeEntry) carried-subtree list and recursive ancestor overlay cannot represent the empty-path carry. Add a carried-root ID/result variant or define an explicit root special case.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed: a carry at the root is its own variant of the merge result (the merged root id as is); the (path, TreeEntry) overlay applies only to non-root carries.
…s, carried-root variant Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
tonibergholm-codento
left a comment
There was a problem hiding this comment.
Design reviewed twice; findings addressed, checks green on 09ddc56.
What
A design record for merge on partial clones, the merge half of what ADR-0048 left refused. Docs only: ADR-0049, its index row, and the ROADMAP entries. No code.
The design in short
A tree-recursive three-way merge that reads only the subtrees that differ. A subtree is carried by id, unread, only when the three sides agree on it by tree id AND it does not intersect a protection rule (or is identical on all three sides). Everything else is enumerated and resolved by the existing leaf rules. Wraps are never pruned when anything was carried. The engine is pull-based (
Needs(ids)), so fills happen outside the store lock. Clean merges come first; conflicts, then cherry-pick/rebase follow; sessions are undecided.How it was reviewed
Two adversarial read-only passes by Codex Sol against the source. The first draft had five blocking flaws, all confirmed in the code and fixed in the record:
protectrecords the rule before it encrypts), so policy-intersecting subtrees are enumerated;ensure_view;The second pass found two more, also fixed: the composite-key regression, and that file/directory collisions are not rejected by the existing writer (the record now requires rejecting them before any write, in both engines).
Needs your call
This record changes behavior on full clones in two small ways (mode-only changes now merge; a file/directory collision fails before any write instead of during materialization). Both are fixes, but they are changes. Say if you would rather keep full clones untouched and apply them to the partial path only.
🤖 Generated with Claude Code
Summary by CodeRabbit