From f40daef1deefda4b76957f5d5728c4175c27be51 Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sat, 28 Mar 2026 18:00:23 +0000
Subject: reachability: Document contract

---
 reachability/reachability.go | 6 +++++-
 reachability/walk.go         | 6 ++++++
 reachability/walk_seq.go     | 2 ++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/reachability/reachability.go b/reachability/reachability.go
index 14bb79cf..2fa29ad1 100644
--- a/reachability/reachability.go
+++ b/reachability/reachability.go
@@ -8,19 +8,23 @@ import (
 
 // Reachability provides graph traversal over objects in one object store.
 //
-// It is not safe for concurrent use.
+// Labels: MT-Unsafe.
 type Reachability struct {
 	store objectstore.ReadingStore
 	graph *commitgraphread.Reader
 }
 
 // New builds a Reachability  over one object store.
+//
+// Labels: Deps-Borrowed.
 func New(store objectstore.ReadingStore) *Reachability {
 	return &Reachability{store: store}
 }
 
 // NewWithCommitGraph builds a Reachability over one object store with an
 // optional commit-graph reader for faster commit-domain traversal.
+//
+// Labels: Deps-Borrowed.
 func NewWithCommitGraph(store objectstore.ReadingStore, graph *commitgraphread.Reader) *Reachability {
 	return &Reachability{store: store, graph: graph}
 }
diff --git a/reachability/walk.go b/reachability/walk.go
index c89d29e9..8e0a0902 100644
--- a/reachability/walk.go
+++ b/reachability/walk.go
@@ -5,6 +5,8 @@ import (
 )
 
 // Walk is one single-use iterator traversal.
+//
+// Labels: MT-Unsafe.
 type Walk struct {
 	reachability *Reachability
 	domain       Domain
@@ -20,6 +22,10 @@ type Walk struct {
 //
 // In DomainCommits, when a commit-graph reader is attached, parent expansion
 // may use commit-graph metadata for speed.
+//
+// Walk retains haves and wants as provided.
+//
+// Labels: Life-Parent.
 func (r *Reachability) Walk(domain Domain, haves, wants map[objectid.ObjectID]struct{}) *Walk {
 	walk := &Walk{
 		reachability: r,
diff --git a/reachability/walk_seq.go b/reachability/walk_seq.go
index 089edc39..e28427a2 100644
--- a/reachability/walk_seq.go
+++ b/reachability/walk_seq.go
@@ -8,6 +8,8 @@ import (
 )
 
 // Seq returns the traversal sequence. It is single-use.
+//
+// Labels: Life-Parent.
 func (walk *Walk) Seq() iter.Seq[objectid.ObjectID] {
 	if walk.seqUsed {
 		return func(yield func(objectid.ObjectID) bool) {
-- 
cgit v1.3.1-10-gc9f91