ref/store: Clarify contract

6 files changed, 28 insertions, 10 deletions

diff --git a/ref/store/batch.go b/ref/store/batch.go
index 6a877a2c..765846d6 100644
--- a/ref/store/batch.go
+++ b/ref/store/batch.go
@@ -9,6 +9,8 @@ import objectid "codeberg.org/lindenii/furgit/object/id"
 //
 // A batch borrows its underlying store and is invalid after that store is
 // closed.
+//
+// Labels: MT-Unsafe.
 type Batch interface {
 	// Create creates one detached reference, requiring that the logical
 	// reference does not already exist.
@@ -38,11 +40,11 @@ type Batch interface {
 	// Apply validates and applies queued operations, returning one result per
 	// queued operation in order. Fatal backend failures are returned separately.
 	//
-	// Apply is terminal. Further use of the batch is undefined behavior.
+	// Apply invalidates the receiver.
 	Apply() ([]BatchResult, error)
 	// Abort abandons the batch and releases any resources it holds.
 	//
-	// Abort is terminal. Further use of the batch is undefined behavior.
+	// Abort invalidates the receiver.
 	Abort() error
 }
 
diff --git a/ref/store/batch_store.go b/ref/store/batch_store.go
index 3ccfdd10..b6cd9adf 100644
--- a/ref/store/batch_store.go
+++ b/ref/store/batch_store.go
@@ -3,5 +3,7 @@ package refstore
 // BatchStore begins non-atomic reference batches.
 type BatchStore interface {
 	// BeginBatch creates one new queued batch.
+	//
+	// Labels: Life-Parent.
 	BeginBatch() (Batch, error)
 }
diff --git a/ref/store/doc.go b/ref/store/doc.go
index 3d6f3908..e022f55b 100644
--- a/ref/store/doc.go
+++ b/ref/store/doc.go
@@ -1,2 +1,6 @@
 // Package refstore provides interfaces for reference storage backends.
+//
+// Concrete implementations generally inherit the contract documented by the
+// interfaces they satisfy. Implementation docs focus on additional guarantees
+// and implementation-specific behavior.
 package refstore
diff --git a/ref/store/reading.go b/ref/store/reading.go
index 3444f07f..ff8ac6f7 100644
--- a/ref/store/reading.go
+++ b/ref/store/reading.go
@@ -3,13 +3,16 @@ package refstore
 import "codeberg.org/lindenii/furgit/ref"
 
 // ReadingStore reads Git references.
+//
+// Labels: MT-Safe.
 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. Returned refs do not borrow the store.
-	// If the reference does not exist, implementations should return
-	// ErrReferenceNotFound.
+	// Implementations should return value forms ([ref.Detached] or [ref.Symbolic]),
+	// not pointer forms. If the reference does not exist, implementations should
+	// return [ErrReferenceNotFound].
+	//
+	// Labels: Life-Parent.
 	Resolve(name string) (ref.Ref, error)
 	// ResolveToDetached resolves a reference name to a detached object ID.
 	//
@@ -19,16 +22,19 @@ type ReadingStore interface {
 	//
 	// ResolveToDetached resolves symbolic references only. It does not imply peeling
 	// annotated tag objects.
+	//
+	// Labels: Life-Parent.
 	ResolveToDetached(name string) (ref.Detached, error)
 	// List returns references matching pattern.
 	//
 	// The exact pattern language is backend-defined.
+	//
+	// Labels: Life-Parent.
 	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.
+	// Labels: Close-UB.
 	Close() error
 }
diff --git a/ref/store/transaction.go b/ref/store/transaction.go
index a70cd3d4..30f6ab50 100644
--- a/ref/store/transaction.go
+++ b/ref/store/transaction.go
@@ -13,6 +13,8 @@ import objectid "codeberg.org/lindenii/furgit/object/id"
 //
 // Symbolic methods operate on the named reference directly, without
 // dereferencing symbolic refs.
+//
+// Labels: MT-Unsafe.
 type Transaction interface {
 	// Create creates one detached reference, requiring that the logical
 	// reference does not already exist.
@@ -41,10 +43,10 @@ type Transaction interface {
 
 	// Commit validates and applies all queued operations atomically.
 	//
-	// Commit is terminal. Further use of the transaction is undefined behavior.
+	// Commit invalidates the receiver.
 	Commit() error
 	// Abort abandons the transaction and releases any resources it holds.
 	//
-	// Abort is terminal. Further use of the transaction is undefined behavior.
+	// Abort invalidates the receiver.
 	Abort() error
 }
diff --git a/ref/store/transactional_store.go b/ref/store/transactional_store.go
index 8f5c32cd..8a061f54 100644
--- a/ref/store/transactional_store.go
+++ b/ref/store/transactional_store.go
@@ -7,5 +7,7 @@ package refstore
 // atomically within that backend.
 type TransactionalStore interface {
 	// BeginTransaction creates one new mutable transaction.
+	//
+	// Labels: Life-Parent.
 	BeginTransaction() (Transaction, error)
 }