From 0f67e6f5f29d765105a1c48017de37df12755417 Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Mar 2026 23:47:55 +0000
Subject: objectstore/packed: Document refresh semantics

---
 objectstore/packed/close.go                 | 1 +
 objectstore/packed/idx_lookup_candidates.go | 7 ++++++-
 objectstore/packed/store.go                 | 2 ++
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/objectstore/packed/close.go b/objectstore/packed/close.go
index f810f42c..f05a8573 100644
--- a/objectstore/packed/close.go
+++ b/objectstore/packed/close.go
@@ -3,6 +3,7 @@ package packed
 // Close releases mapped pack/index resources associated with the store.
 //
 // Store borrows its root, so Close does not close it.
+// Close releases cached pack/index mappings retained by the store.
 //
 // Repeated calls to Close are undefined behavior.
 func (store *Store) Close() error {
diff --git a/objectstore/packed/idx_lookup_candidates.go b/objectstore/packed/idx_lookup_candidates.go
index e69d07d7..a2de262a 100644
--- a/objectstore/packed/idx_lookup_candidates.go
+++ b/objectstore/packed/idx_lookup_candidates.go
@@ -22,7 +22,12 @@ type candidateSnapshot struct {
 	candidateByPack map[string]packCandidate
 }
 
-// Refresh rescans objects/pack and atomically installs a fresh candidate list.
+// Refresh rescans objects/pack and atomically installs a fresh candidate list
+// for future lookups.
+//
+// Refresh does not invalidate existing readers. Cached pack/index mappings,
+// including ones for previously visible candidates, may be retained until
+// Close.
 func (store *Store) Refresh() error {
 	store.refreshMu.Lock()
 	defer store.refreshMu.Unlock()
diff --git a/objectstore/packed/store.go b/objectstore/packed/store.go
index 61ccdb9a..fc3f57d4 100644
--- a/objectstore/packed/store.go
+++ b/objectstore/packed/store.go
@@ -11,6 +11,8 @@ import (
 )
 
 // Store reads Git objects from pack/index files under an objects/pack root.
+//
+// Store borrows its root. Cached pack/index mappings are retained until Close.
 type Store struct {
 	// root is the borrowed objects/pack capability used for all file access.
 	root *os.Root
-- 
cgit v1.3.1-10-gc9f91