From 13507b7704415332e2b00f5f4d291f3be8bd18fa Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Mar 2026 23:51:01 +0000
Subject: receivepack: Lifecycle/ownership docs

---
 receivepack/hook.go        | 6 +++++-
 receivepack/options.go     | 9 ++++++++-
 receivepack/receivepack.go | 3 +++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/receivepack/hook.go b/receivepack/hook.go
index 5f98a538..fcf2cd37 100644
--- a/receivepack/hook.go
+++ b/receivepack/hook.go
@@ -30,6 +30,9 @@ type UpdateDecision struct {
 
 // HookRequest is the input presented to a receive-pack hook before quarantine
 // promotion and ref updates.
+//
+// Refs, ExistingObjects, and QuarantinedObjects are borrowed and are only
+// valid for the duration of the hook call.
 type HookRequest struct {
 	Refs               refstore.ReadingStore
 	ExistingObjects    objectstore.Store
@@ -43,7 +46,8 @@ type HookRequest struct {
 //
 // The hook runs after pack ingestion into quarantine and before quarantine
 // promotion or ref updates. The returned decisions must have the same length as
-// HookRequest.Updates.
+// HookRequest.Updates. Hook borrows the data and stores in HookRequest only for
+// the duration of the call.
 type Hook func(context.Context, HookRequest) ([]UpdateDecision, error)
 
 func translateHook(hook Hook) service.Hook {
diff --git a/receivepack/options.go b/receivepack/options.go
index 7328f770..860f29c1 100644
--- a/receivepack/options.go
+++ b/receivepack/options.go
@@ -9,6 +9,12 @@ import (
 )
 
 // Options configures one receive-pack invocation.
+//
+// ReceivePack borrows all configured dependencies.
+//
+// Refs and ExistingObjects are required and must be non-nil.
+// ObjectsRoot is required if the invocation may need to ingest or promote a
+// pack.
 type Options struct {
 	// GitProtocol is the raw Git protocol version string from the transport,
 	// such as "version=1".
@@ -27,7 +33,8 @@ type Options struct {
 	// directories moved from quarantine into the permanent object store.
 	PromotedObjectPermissions *PromotedObjectPermissions
 	// Hook, when non-nil, runs after pack ingestion into quarantine and before
-	// quarantine promotion or ref updates.
+	// quarantine promotion or ref updates. Hook is borrowed for the duration of
+	// ReceivePack.
 	Hook Hook
 	// Agent is the receive-pack agent string advertised via capability.
 	//
diff --git a/receivepack/receivepack.go b/receivepack/receivepack.go
index 8103ad1f..98bb3030 100644
--- a/receivepack/receivepack.go
+++ b/receivepack/receivepack.go
@@ -19,6 +19,9 @@ import (
 // feels a bit ugly.
 
 // ReceivePack serves one receive-pack session over r/w.
+//
+// ReceivePack borrows r, w, and all dependencies reachable through opts for
+// the duration of the call. It does not close any of them.
 func ReceivePack(
 	ctx context.Context,
 	w pktline.WriteFlusher,
-- 
cgit v1.3.1-10-gc9f91