Skip to content

rfc: branch operations v2 - #677

Draft
aaltshuler wants to merge 2 commits into
mainfrom
codex/branch-ops-v2
Draft

rfc: branch operations v2#677
aaltshuler wants to merge 2 commits into
mainfrom
codex/branch-ops-v2

Conversation

@aaltshuler

Copy link
Copy Markdown
Contributor

What & why

Branch operations still reconstruct growing manifest history, and ancestry-eligible merges can replay source data into target-owned datasets. Propose RFC 0060 to replace current-state reconstruction with explicit immutable graph snapshots and conditional adoption commits, preserving the target's first-parent history.

The draft defines one current __manifest authority for logical refs, exact retained snapshot roots, independent writes after adoption, graph-wide immutable tags, historical reads/forks, merge preview, and safe logical deletion. Whole-state restore follows; rebase, cherry-pick, and selective revert require a later logical-change replay contract.

This PR changes only the RFC and registry. It remains draft / not-started and does not accept a new format or activate runtime behavior.

Backing issue / RFC

Related work: accepted RFC 0057 / #638, branch-context and retained-ancestry work in #662, and bounded merge preparation in #668. The RFC records scoped relationships to existing authority, retention, recovery, feed, and GQ decisions. No existing decision is superseded by this draft.

Notes for reviewers

  • The candidate uses strict native Lance Overwrite with engine-owned fresh retries. Cold latest-version discovery, central-CAS contention, and retained metadata amplification require qualification.
  • Adoption must preserve source isolation, first writes, tags, Blob dependencies, and deletion/cleanup safety. Initial destructive cleanup requires a quiesced graph; no new distributed fencing is claimed.
  • Existing-graph cutover must preserve selected contents and complete parent-record closure, or explicitly refuse/reset identities and feed baselines.
  • The completed AWS campaign is divergent-merge bottleneck evidence: 50 native-S3 measurements and eight NVMe controls. It does not measure promotion speedup. Small eligible fixtures, full first-use/reclamation lifecycles, and activation gates are specified separately.

Checklist

  • One focused RFC and registry update.
  • Tests for behavior changes: N/A; documentation only. Existing test owners and future qualification gates are specified.
  • Public supported-behavior docs: N/A; no new behavior ships.
  • Reviewed against architectural invariants and pinned Lance 11 surfaces; unresolved representation/protocol gates remain explicit.

Local verification

  • python3 scripts/check-docs.py — passed (132 Markdown files).
  • bash scripts/check-agents-md.sh — passed.
  • typos docs/rfcs/0060-branch-ops-v2.md docs/rfcs/README.md — passed.
  • git diff --cached --check — passed.
  • Independent design and benchmark-evidence review — completed.
  • Rust builds, tests, DST, and benchmarks — not rerun for this documentation-only PR.

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.

1 participant