From d314d1f7e933ca83081eec289aa0cb6e75a7eeac Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Mar 2026 17:33:27 +0000
Subject: objectstore{,/packed}: Document lifetime and integrity behavior

---
 objectstore/packed/read_reader.go | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

(limited to 'objectstore/packed/read_reader.go')

diff --git a/objectstore/packed/read_reader.go b/objectstore/packed/read_reader.go
index cbecaf2c..5c9ac8f4 100644
--- a/objectstore/packed/read_reader.go
+++ b/objectstore/packed/read_reader.go
@@ -12,9 +12,18 @@ import (
 	packfmt "codeberg.org/lindenii/furgit/packfile"
 )
 
-// ReadReaderContent reads an object's type, declared content size, and content stream.
+// ReadReaderContent reads an object's type, declared content size, and content
+// stream.
 //
 // The caller must close the returned reader.
+//
+// For base pack entries, the returned reader borrows store-owned mapped pack
+// data and is only valid until the store is closed.
+//
+// Close releases reader-local resources only. It does not drain unread data for
+// additional validation. In particular, malformed trailing compressed data,
+// trailing bytes past the declared object size, and the zlib Adler-32 trailer
+// may go unverified unless the caller reads to io.EOF.
 func (store *Store) ReadReaderContent(id objectid.ObjectID) (objecttype.Type, int64, io.ReadCloser, error) {
 	loc, err := store.lookup(id)
 	if err != nil {
@@ -49,6 +58,14 @@ func (store *Store) ReadReaderContent(id objectid.ObjectID) (objecttype.Type, in
 // ReadReaderFull reads a full serialized object stream as "type size\0content".
 //
 // The caller must close the returned reader.
+//
+// For base pack entries, the returned reader borrows store-owned mapped pack
+// data and is only valid until the store is closed.
+//
+// Close releases reader-local resources only. It does not drain unread data for
+// additional validation. In particular, malformed trailing compressed data,
+// trailing bytes past the declared object size, and the zlib Adler-32 trailer
+// may go unverified unless the caller reads to io.EOF.
 func (store *Store) ReadReaderFull(id objectid.ObjectID) (io.ReadCloser, error) {
 	loc, err := store.lookup(id)
 	if err != nil {
-- 
cgit v1.3.1-10-gc9f91