From 8f577284f47f699855dcb3ceda21aa9d8be77c2f Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Mar 2026 17:27:37 +0000
Subject: objectstore{,/loose}: Document contracts more clearly

---
 objectstore/objectstore.go | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

(limited to 'objectstore/objectstore.go')

diff --git a/objectstore/objectstore.go b/objectstore/objectstore.go
index 2592c1b1..f152a7f0 100644
--- a/objectstore/objectstore.go
+++ b/objectstore/objectstore.go
@@ -25,27 +25,47 @@ type Store interface {
 	// In a valid repository, hashing this payload with the same algorithm yields
 	// the requested object ID. Readers should treat this as a repository
 	// invariant and should not re-verify it on every read.
+	//
+	// Any read-time integrity verification beyond producing this payload is
+	// implementation-defined.
 	ReadBytesFull(id objectid.ObjectID) ([]byte, error)
 
 	// ReadBytesContent reads an object's type and content bytes.
+	//
+	// Any read-time integrity verification beyond producing this payload is
+	// implementation-defined.
 	ReadBytesContent(id objectid.ObjectID) (objecttype.Type, []byte, error)
 
 	// ReadReaderFull reads a full serialized object stream as "type size\0content".
+	//
 	// Caller must close the returned reader.
+	//
+	// Any read-time integrity verification performed while producing the stream
+	// is implementation-defined.
 	ReadReaderFull(id objectid.ObjectID) (io.ReadCloser, error)
 
 	// ReadReaderContent reads an object's type, declared content length,
 	// and content stream.
+	//
 	// Caller must close the returned reader.
+	//
+	// Any read-time integrity verification performed while producing the stream
+	// is implementation-defined.
 	ReadReaderContent(id objectid.ObjectID) (objecttype.Type, int64, io.ReadCloser, error)
 
 	// ReadSize reads an object's declared content length.
 	//
 	// This is equivalent to ReadHeader(...).size and may be cheaper than
 	// ReadHeader when callers do not need object type.
+	//
+	// Any read-time integrity verification performed to produce the size is
+	// implementation-defined.
 	ReadSize(id objectid.ObjectID) (int64, error)
 
 	// ReadHeader reads an object's type and declared content length.
+	//
+	// Any read-time integrity verification performed to produce the header is
+	// implementation-defined.
 	ReadHeader(id objectid.ObjectID) (objecttype.Type, int64, error)
 
 	// Refresh updates any backend-local discovery/cache view of on-disk objects.
@@ -54,6 +74,9 @@ type Store interface {
 	Refresh() error
 
 	// Close releases resources associated with the backend.
+	//
+	// Repeated calls to Close are undefined behavior unless the implementation
+	// explicitly documents otherwise.
 	Close() error
 }
 
-- 
cgit v1.3.1-10-gc9f91