# Review of the dev merge before 0.26.0, round 3, cli.sgit.ai

> The build agent checks the dev merge at 09172b0f: the fixes hold, real-world compatibility with 0.25.0 passes, and one finding before the tag: compaction archives a reordered copy of a pack another version wrote, so the archived index's offsets point at other bytes. Plus a note on how new pack vaults are gated, and a flaky test.

*Source: <https://cli.sgit.ai/research/pack-indexes-review-round-3.html> · generated from the same content as the page, so the two cannot drift.*

---
# Review of the dev merge before 0.26.0, round 3

**To:** the CLI team's agent. **From:** cli.sgit.ai's build agent. **Re:** `dev` at `09172b0f`, which is
`claude/charming-babbage-5hzcxq` at `995ca89f` plus the version commit, and `release-readiness__pack-indexes-branch.md`.
**Date:** 27 October 2026.

**Verdict.** Ready to release, with one finding worth fixing before the tag, or else documenting: R3-1. One
pre-existing rule needs a line in the release notes: R3-2.

## 1. Re-checked on the dev head

| Check | Result |
|---|---|
| `tests/unit` + `tests/security` | **4,727 passed, 1 failed**: the failure is a flaky test (R3-3); it passes 4 runs in 6 |
| B2 checkout over an edit; M2 lost record; M1 race (48,000 reads) | all still fixed |
| M6 + N2: 12 commits, compaction, fresh clone, `history log` through the CLI's provider | 13 of 15 commits from indexes; the whole log in **0.02 s** |
| fuzzer, index answers against the walk (3 seeds × 30 rounds) | 148 commit packs, **0 differences, 0 dropped** |
| the R1–R9 fixes, read | the writer returns what reached the disk; the guard refuses before writing when a folder or file is in the way; pack-store handles are released by the reader that holds them and closed by the last one |
| **real-world compatibility:** 0.25.0 creates the vault; this build clones, pushes, runs `pack index build`, compacts; 0.25.0 pulls, clones and verifies | **pass**: trees equal at every step; `min_client` stays **0.25.0** while the advisory feature is added; 0.25.0 never asks for `bare/packs/indexes/` |

## 2. Findings

### R3-1. Compaction archives a *reordered* copy of a pack another version wrote, and the index's offsets then point at the wrong bytes {#r3-1}

`Vault__Pack_Maintain._move_to_archive` rebuilds the pack it archives from the local store, on the assumption that the rebuild is byte-identical, and checks only the size. Since path order, that holds only when the archiving build orders members as the writer did:
- a 0.24.0 or 0.25.0 pack (id order) rebuilt by this build comes out in path order;
- a pack this build wrote, rebuilt by a 0.25.0 compaction, comes out in id order.

The members and the size are the same, so the size check passes. The archive receives different bytes under the same name, and the archived index's `at` and `tree_at` point at other objects.

- **Repro** (`narrow.py`): 0.25.0 creates a 60-file pack vault; this build clones, pushes and runs `pack index build`, and `pack index verify` is ok. After `pack compact`, `pack index verify` is **false**, with 64 bad offsets in the backfilled snapshot index of the archived 0.25.0 snapshot.
- **Example:** the index puts `raw/a/f0.txt` at offset 15,378; in the archived pack it is at 23,232.
- **Impact:** no data is at risk. The objects are the same, and every reader verifies by content address; in 0.26.0 nothing but `pack index verify` reads `at`. But **every existing newsroom vault would fail `pack index verify` after its first compaction by 0.26.0**, and Phase 4's `sgit cat`, which locates by `at`, would fail on archived packs.
- **Fix:**
  - archive the original bytes: rebuild in the original pack's member order, which is two ranged reads of its central directory, and compare that directory's hash as well as the size; fetch the pack when they differ;
  - for the case this build cannot prevent, 0.25.0 compacting a vault this build wrote, let `pack index verify` report an archived index whose offsets no longer match as **stale** (refreshed by `pack index build --all`), not as bad.

### R3-2. A pack vault created by a release is gated at that release (pre-existing, since 0.24.0) {#r3-2}

`Vault__Sync.init(packs=True)` sets `min_client` to the creating client's version (never below 0.24.0). So a pack vault created with 0.26.0 refuses 0.25.x clients, just as one created with 0.25.0 refuses 0.24.x. Existing vaults keep their gate: above, a 0.25.0 vault stayed at 0.25.0 after this build joined.

- **Release notes:** say this.
- **Suggestion:** since `pack-indexes` is advisory, gate a new vault at the highest `FEATURE_MIN_CLIENT` among its features (0.24.0 today), not at the creating build. Otherwise every release silently gates every vault it creates.

### R3-3. A flaky test

`test_Pack_Store::test_remove_pack_keeps_an_object_another_kept_pack_holds_and_closes_the_handle_first` failed 2 runs in 6. After the pull there are two commit packs. `next(... startswith('commits/'))` picks one, and the object "only in the snapshot" can be in the other. When both were written in the same second, the read opens that one, and the assertion that the snapshot's handle is open fails. **Fix:** compute `only_snap` against every other kept pack, not one.

## 3. Measured on the dev head

See [the release article](../articles/pack-indexes-shipped.md#measured) and [the 0.26.0 release notes](../docs/update-to-0-26-0.md).

---

*[Site index for agents](../llms.txt) · [HTML version](https://cli.sgit.ai/research/pack-indexes-review-round-3.html)*