object/store: Refine docs

1 files changed, 10 insertions, 0 deletions

diff --git a/object/store/doc.go b/object/store/doc.go
index 943dbea4..4e05f59c 100644
--- a/object/store/doc.go
+++ b/object/store/doc.go
@@ -1,5 +1,15 @@
 // Package objectstore provides interfaces for object storage backends.
 //
+// Object stores only respond to object-ID queries in terms of headers (type
+// and size), raw bytes, and streaming payloads, but they do not parse commits,
+// trees, blobs, or tags into typed values. Turning stored objects into typed
+// objects is the job of [codeberg.org/lindenii/furgit/object/fetch].
+//
+// This package also does not define a unified writing-store interface.
+// Backends have very different write models: writing one loose object is
+// natural, while writing one object into a packfile backend is wasteful.
+// A variety of writing interfaces may be added later.
+//
 // Concrete implementations generally inherit the contract documented by the
 // interfaces they satisfy. Implementation docs focus on additional guarantees
 // and implementation-specific behavior.