repository: Clarify ownership

5 files changed, 19 insertions, 2 deletions

diff --git a/repository/objects.go b/repository/objects.go
index b7ca2094..965a9f68 100644
--- a/repository/objects.go
+++ b/repository/objects.go
@@ -68,6 +68,10 @@ func openObjectStore(
 
 // Objects returns the configured object store.
 //
+// The returned store is owned by Repository and borrows repository-managed
+// resources. Callers must not close it directly, and it must not be used after
+// Close.
+//
 //nolint:ireturn
 func (repo *Repository) Objects() objectstore.Store {
 	return repo.objects
diff --git a/repository/refs.go b/repository/refs.go
index a3e2cfb8..83afe047 100644
--- a/repository/refs.go
+++ b/repository/refs.go
@@ -4,6 +4,10 @@ import "codeberg.org/lindenii/furgit/refstore"
 
 // Refs returns the configured ref store.
 //
+// The returned store is owned by Repository and borrows repository-managed
+// resources. Callers must not close it directly, and it must not be used after
+// Close.
+//
 //nolint:ireturn
 func (repo *Repository) Refs() refstore.ReadWriteStore {
 	return repo.refs
diff --git a/repository/repository.go b/repository/repository.go
index c56827cd..376c9bd7 100644
--- a/repository/repository.go
+++ b/repository/repository.go
@@ -16,6 +16,10 @@ import (
 //
 // Open expects a root for the Git directory itself:
 // a bare repository root or a non-bare ".git" directory.
+//
+// Accessors such as Objects, Refs, Resolver, and LooseStoreForWriting return
+// views backed by resources owned by Repository. Those values borrow the
+// repository's stores and filesystem roots and must not be used after Close.
 type Repository struct {
 	config *config.Config
 	algo   objectid.Algorithm
diff --git a/repository/resolver.go b/repository/resolver.go
index faeb8837..ed87fa09 100644
--- a/repository/resolver.go
+++ b/repository/resolver.go
@@ -4,8 +4,8 @@ import "codeberg.org/lindenii/furgit/object/resolve"
 
 // Resolver returns an object resolver backed by the repository's object store.
 //
-// The returned resolver is ready for use and does not take ownership of the
-// repository or its underlying object store.
+// The returned resolver is ready for use, borrows the repository's object
+// store, does not need closing, and must not be used after Close.
 func (repo *Repository) Resolver() *resolve.Resolver {
 	return resolve.New(repo.objects)
 }
diff --git a/repository/write_loose.go b/repository/write_loose.go
index bd8d7f57..db57c9c6 100644
--- a/repository/write_loose.go
+++ b/repository/write_loose.go
@@ -4,6 +4,11 @@ import (
 	objectloose "codeberg.org/lindenii/furgit/objectstore/loose"
 )
 
+// LooseStoreForWriting returns the repository's loose-object writer.
+//
+// The returned store is owned by Repository and borrows repository-managed
+// resources. Callers must not close it directly, and it must not be used after
+// Close.
 func (repo *Repository) LooseStoreForWriting() *objectloose.Store {
 	return repo.objectsLoose
 }