From afd58b4e5882402d606728e4f2ee8e5cb2354939 Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Mar 2026 23:24:18 +0000
Subject: refstore: Update invariants

---
 refstore/batch.go       | 3 +++
 refstore/reading.go     | 4 +++-
 refstore/transaction.go | 3 +++
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/refstore/batch.go b/refstore/batch.go
index b170916b..01da6c90 100644
--- a/refstore/batch.go
+++ b/refstore/batch.go
@@ -6,6 +6,9 @@ import "codeberg.org/lindenii/furgit/objectid"
 //
 // Unlike Transaction, Batch may reject some queued operations while still
 // applying others successfully when Apply runs.
+//
+// A batch borrows its underlying store and is invalid after that store is
+// closed.
 type Batch interface {
 	// Create creates one detached reference, requiring that the logical
 	// reference does not already exist.
diff --git a/refstore/reading.go b/refstore/reading.go
index 98a5bd51..3444f07f 100644
--- a/refstore/reading.go
+++ b/refstore/reading.go
@@ -7,7 +7,7 @@ type ReadingStore interface {
 	// Resolve resolves a reference name to either a symbolic or detached ref.
 	//
 	// Implementations should return value forms (ref.Detached or ref.Symbolic),
-	// not pointer forms.
+	// not pointer forms. Returned refs do not borrow the store.
 	// If the reference does not exist, implementations should return
 	// ErrReferenceNotFound.
 	Resolve(name string) (ref.Ref, error)
@@ -26,6 +26,8 @@ type ReadingStore interface {
 	List(pattern string) ([]ref.Ref, error)
 	// Close releases resources associated with the store.
 	//
+	// Transactions and batches borrowing the store are invalid after Close.
+	//
 	// Repeated calls to Close are undefined behavior unless the implementation
 	// explicitly documents otherwise.
 	Close() error
diff --git a/refstore/transaction.go b/refstore/transaction.go
index fc0a8d76..5d090696 100644
--- a/refstore/transaction.go
+++ b/refstore/transaction.go
@@ -4,6 +4,9 @@ import "codeberg.org/lindenii/furgit/objectid"
 
 // Transaction stages reference updates for one atomic commit.
 //
+// A transaction borrows its underlying store and is invalid after that store
+// is closed.
+//
 // Ordinary methods operate in dereference mode if name resolves to
 // a symbolic ref, the operation applies to the final referent rather
 // than to the symbolic ref itself.
-- 
cgit v1.3.1-10-gc9f91