Skip to content

docs(adr): propose ADR-0049 merge on partial clones (P37c) - #181

Merged
tonibergholm-codento merged 6 commits into
mainfrom
p37c-adr
Oct 17, 2026
Merged

tonibergholm-codento merged 6 commits into
mainfrom
p37c-adr

Conversation

@tonibergholm

@tonibergholm tonibergholm commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

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:

  • id-carry compared whole entries while flatten compares blob id only, so a mode-only change picked a different winner (now content and mode are separate dimensions in both engines, a small deliberate behavior change on full clones);
  • "newly covered by a rule" is unsound because a side can already hold plaintext under its own rule (protect records the rule before it encrypts), so policy-intersecting subtrees are enumerated;
  • the conflict state contract was missing and could put plaintext in the CAS, so conflicts are deferred to 37c-iii behind an amendment;
  • a fill callback inside the merge would deadlock on the store mutex, and the final view also needs ensure_view;
  • tree-id equivalence with flatten does not hold for empty directories, so equivalence is defined on file sets.

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

  • Documentation
    • Added a proposed design for merging partial clones, including how matching subtrees, protected regions, and missing content are handled.
    • Clarified that partial-clone merges initially support clean merges only; merges with conflicts are refused before outputs are written.
    • Updated the roadmap to distinguish merge behavior from other partial-clone operations and their planned phases.

tonibergholm and others added 3 commits October 17, 2026 11:41
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>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-17T09:07:48.316136Z 09ddc56 New commits
🔒 Security Review ✅ Completed 2026-10-17T09:06:51.324343Z 09ddc56 New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d4631180-b098-4b9d-a394-4124c2ab3b57
📥 Commits

Reviewing files that changed from the base of the PR and between e91c4ad and 09ddc56.

📒 Files selected for processing: 3
  • ROADMAP.md
  • docs/adr/0049-merge-on-partial-clones.md
  • docs/adr/README.md
+------------------------------------------+
| Thread behaviour? I don't even know her. |
+------------------------------------------+
  \
   \     /)/)
        ( '')
        /  |
      o(___)
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread ROADMAP.md Outdated
Comment on lines +564 to +565
and fills (lazy) or refuses (otherwise) only the region where all three sides
differ. Clean merges first, then conflicts, then cherry-pick/rebase; sessions

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 tonibergholm-codento left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design reviewed twice; findings addressed, checks green on 09ddc56.

@tonibergholm-codento
tonibergholm-codento merged commit 2fe28e3 into main Oct 17, 2026
7 of 8 checks passed
@tonibergholm
tonibergholm deleted the p37c-adr branch October 17, 2026 09:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants