fix: fence stale tiered re-tier metadata writes

[perfloop]

A delayed tiered GET could register its background re-tier after a successful local PUT and use the PUT's newer metadata version to remove or relabel the entry. The worker now carries the marker version observed by the GET, refuses a pre-fetch mismatch, and uses that original version for every metadata mutation. This keeps local writes authoritative while unchanged markers continue to heal and converge. The README and tiered-mode guide now describe this guarantee. This is a source-derived race, not an observed production incident.

The original-defect test is TestTieredRetierDelayedRegistrationPreservesLocalPut; its two schedules cover a 404 and a different-ETag 200, including a same-content successor PUT. The preservation test is TestTieredRetier404ConvergesUnchangedMarker. Existing tests cover healing, replacement convergence, cancellation, and the held-write claim.

make lint-ci, make build, make test, and make test-race passed locally.

The tiered S3 compatibility profile was not run here: make s3-test-local-tiered and S3TEST_PROFILE=tiered make s3-tests require Tigris credentials for a live upstream.

The production frequency of this source-derived race is unmeasured.

satisfied

violated

25edfad56c72d7a7bc56daab8dac642c45faaa03

---

Generated by Perfloop.

---

Note

Medium Risk
Changes authoritative tiered metadata CAS behavior for background re-tier; correctness fix with targeted tests, but races in tiered mode are sensitive.

Overview
Fixes a tiered-mode race where a delayed background re-tier could register after a successful local PUT and mutate metadata using a newer version token—removing or relabeling the local write.

Re-tier-on-read now carries the marker version from the triggering GET into maybeRetierOnRead. The worker checks that snapshot before upstream work and uses that same version for every PutMetaIfVersion / DeleteMetaIfVersion, so stale heals cannot overwrite a later local PUT (including same-content MD5 ETag cases). Unchanged-marker 404 convergence is preserved.

README and docs/tiered-mode.md document the version-bound re-tier guarantee. Tests add a gated metadata client and scenarios for delayed registration plus unchanged-marker 404 convergence.

^{Reviewed by Cursor Bugbot for commit 48f6083. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Confidence Score: 5/5

[High impact] This PR appears safe to merge; stale background work cannot adopt a later write's metadata version.

Summary

The worker now carries the metadata version seen by the triggering GET instead of adopting a newer version before fetching.

• Background re-tier work can no longer replace metadata from a later write.

No actionable issues found. Tests were inspected but not run during this review.

_{Reviews (1) · Last reviewed commit: "docs: describe tiered write metadata aut..." · Reviewed by Greptile}