@@ -268,6 +268,17 @@ func writePack(st storage.Storer, rd io.Reader) error {
 		return err
 	}
 
+	// A writer that reads the pack itself finds its end in the same pass that
+	// stores it. The Scanner below cannot do that in bounded memory: over a
+	// reader that cannot seek, it buffers every object's whole inflated body.
+	if pr, ok := w.(packReader); ok {
+		if err := pr.ReadPack(rd); err != nil {
+			_ = w.Close()
+			return err
+		}
+		return w.Close()
+	}
+
 	sc := packfile.NewScanner(io.TeeReader(rd, w), sopts...)
 	for sc.Scan() {
 	}
@@ -278,6 +289,12 @@ func writePack(st storage.Storer, rd io.Reader) error {
 	return w.Close()
 }
 
+// packReader is the optional PackfileWriter surface that reads exactly one
+// packfile from r and stops at its trailer. The tigris storer has one.
+type packReader interface {
+	ReadPack(r io.Reader) error
+}
+
 // sidebandProgress writes to the sideband progress channel (band 2), which the
 // git client renders as "remote: " lines.
 type sidebandProgress struct {
 
@@ -339,26 +339,47 @@ caps below set how much one container holds.
 It does not store the git pack format. Git packs use delta compression, so one
 read would have to resolve a chain of deltas.
 
-`PackfileWriter` instead writes the incoming pack to a scratch
-`storage/filesystem.Storage` on a local temp directory. That storage decodes
-the pack for us, so this package holds no pack-parsing code.
-
-The writer makes two passes. The first reads the hash, type, size, and delta
-base of every object, then orders them so a base always precedes the delta
-that needs it — `IterEncodedObjects` returns hash order, which gives no such
-guarantee. The second pass copies each payload into a flat `packs/<id>.bin`
-and adds one record to `packs/<id>.cue`. A record holds the hash, the type,
-the payload codec, the offset, the stored length, the raw size, and the base
-hash. `<id>` is the hex SHA-256 of the `.bin`, so the name doubles as a
-checksum. Both files upload through the same uploader as loose objects, so the
-existing `SetReference` flush covers them.
+`PackfileWriter` decodes the pack itself, in `indexpack.go`. That file is a
+small version of `git index-pack`. Its memory does not grow with the size of
+the history or with the size of one object. See
+[the plan](../plans/push-memory.md) for the measurements.
+
+The writer makes two passes:
+
+1. `scanPack` reads the pack as it arrives. It stages the bytes in a temp
+   file, verifies the trailer checksum, and keeps a small index entry for each
+   object: the offset, the size, the type, and the base of a delta. It keeps
+   no body.
+2. The resolver walks each delta tree depth first, from its base, so a base
+   always goes into a container before its deltas. It copies each payload into
+   a flat `packs/<id>.bin` and adds one record to `packs/<id>.cue`.
+
+A record holds the hash, the type, the payload codec, the offset, the stored
+length, the raw size, and the base hash. `<id>` is the hex SHA-256 of the
+`.bin`, so the name is also a checksum. Both files upload through the same
+uploader as loose objects, so the existing `SetReference` flush covers them.
+
+A body stays in memory only while a delta below it needs it as a base. A
+body goes to a temp file when it is larger than `bodyMemLimit` (8 MiB), or when
+the bodies in memory would pass `bodyMemBudget` (64 MiB). The delta applier
+reads its base through `io.ReaderAt`, so a base on disk is never loaded whole.
+
+`cmd/objgitd`'s `writePack` calls `ReadPack` when the writer has it. `ReadPack`
+finds the end of the pack in the same pass that stages it. `packScanner` is an
+`io.ByteReader`, so zlib never reads past the pack. On git:// and SSH the
+client keeps the connection open after the pack, so a read past the pack
+blocks.
 
 A payload is the object, or the delta the pushing client already computed for
 it. Keeping that delta is what stops every later clone from deriving one
 again: `Storer` implements `storer.DeltaObjectStorer`, so go-git's packer
 reuses the stored delta instead of running its rolling-hash search. See
 [the backend reference](../reference/tigris-backend.md#how-a-read-rebuilds-a-delta).
 
+A read walks at most `maxDeltaDepth` (50) delta links, and a client can send
+chains of up to 4095 links. The writer therefore stores an object whole when
+its stored chain is already 50 links long.
+
 A delta is only kept when its base lands in the same container. When a
 container seals between the two, the writer stores the whole object instead.
 That costs a few deltas at each boundary and buys back the rule that every
@@ -417,6 +438,41 @@ Reads check three tiers, in this order:
 The pack index is built once for each `Storer`, from the `packs/*.cue` files.
 Those files are small, and no `.bin` body is read to build it.
 
+### The pack index (`packtable.go`)
+
+The index is a list of sorted tables, and not a map. A table holds the hashes
+of its records in one `[]byte`, and a 40-byte `tableRec` for each record. That
+is about 60 bytes for each object with SHA-1. The map it replaced took about
+210 bytes. For golang/go, a cold build holds 40 MiB of tables, against about
+180 MiB of map.
+
+A `tableRec` holds a pack number and not a pack id, and the base of a delta as
+a record number and not a hash. A base in another table goes in the small
+`farBase` map. The writer keeps a base and its delta in one container, so that
+map is almost always empty.
+
+The cold build parses each `.cue` into a table and then drops its records. It
+then merges all of the tables into one. Each container that a push registers
+adds one table. When there are more than `maxPackTables` (16) tables, the index
+merges them into one, so a lookup does at most 16 binary searches. A lookup
+searches from the newest table to the oldest, so the newest record of a hash
+wins.
+
+A table never changes after it is built. A `packSnapshot` therefore shares the
+table list, the pack ids, and the dead set with the index, and costs no copy.
+The index never edits these in place. It only appends past the length that a
+snapshot sees, or it replaces the slice or the map.
+
+`deregister` takes only a pack id. It drops a table that holds only that pack.
+In a merged table it adds the pack to the dead set, a lookup skips the record,
+and the next merge drops it. `packJob` therefore keeps no `cueRecord`s while
+its upload runs.
+
+`IterEncodedObjects` walks `packSnapshot.order`, which costs 8 bytes for each
+object, in pack order and then offset order. It yields a hash only from the
+record that the lookup returns, so it needs no set of hashes that it has
+already yielded.
+
 A packed read is one ranged `GetObject` over the record's `stored` span. There
 is no delta chain to reconstruct. When the record names the zstd codec, the
 read decompresses one frame; otherwise the bytes are already the object.
 
@@ -0,0 +1,229 @@
+# Plan: bounded memory for large pushes
+
+## Goal
+
+A push of any repository, of any size, must complete in bounded memory. The
+memory that one push uses must not grow with the size of the history, and must
+not grow with the size of one object.
+
+## The problem
+
+A push of golang/go (465 MiB pack, 708,000 objects) used more than 21 GiB of
+heap. On a laptop it filled swap and did not complete. A push of Xe/x (50 MB
+pack, 21,000 objects) used 516 MiB.
+
+Almost all of that memory was in go-git, and not in this repository.
+
+`PackfileWriter` gave the pushed pack to a scratch go-git
+`filesystem.Storage`. That storage indexes the pack with a `packfile.Parser`
+that has no storage attached. Without a storage, the parser does not use its
+low-memory mode. It keeps the inflated body of every base object and every
+resolved delta until the whole pack is parsed. Memory therefore grew with the
+uncompressed size of the full history.
+
+Three smaller costs came after the parse:
+
+- The plan pass called `IterEncodedObjects`, which loads each full object to
+  read its hash, type, and size.
+- Eight workers opened eight more copies of the scratch index to find delta
+  bases.
+- The container walk resolved each object again through the go-git packfile
+  reader.
+
+A fourth cost was in `cmd/objgitd/receivepack.go`. `writePack` ran a go-git
+`Scanner` over the socket to find the end of the pack. That reader cannot
+seek, so the scanner buffered the full inflated body of each object. One large
+blob therefore needed its full size in memory.
+
+## Phase 1: replace the scratch storage (done)
+
+`internal/storage/tigris/indexpack.go` is a small version of `git index-pack`.
+It does the work in two passes.
+
+1. `scanPack` reads the pack once, as it arrives. It stages the bytes in a
+   temp file and verifies the trailer checksum. For each object it keeps about
+   60 bytes: the offset, the size, the type, and the base of a delta. It
+   inflates each entry to find where the entry ends, but it keeps no body.
+2. The resolver walks each delta tree depth first, from its base. A body lives
+   only while a delta below it needs it as a base. A linear chain therefore
+   holds two bodies at a time. Each object is inflated, resolved, and hashed
+   once.
+
+A body stays in memory when it is 8 MiB or less, and when all bodies in memory
+stay under 64 MiB. Other bodies go to a temp directory for the push. The delta
+applier reads its base through `io.ReaderAt`, so it never loads a base on disk
+into memory.
+
+`writePack` now hands the stream to the storer through an optional
+`ReadPack(io.Reader) error` method. The storer finds the end of the pack in the
+same pass that stages and indexes it. `packScanner` is an `io.ByteReader`, so
+zlib does not read past the end of the pack. This matters on git:// and SSH,
+where the client keeps the connection open after the pack.
+
+### Results of phase 1
+
+The numbers come from a local harness. It feeds a real pack to
+`PackfileWriter` over an S3 fake that discards bodies.
+
+| Push                      | Before                | After            |
+| ------------------------- | --------------------- | ---------------- |
+| golang/go, peak heap      | more than 21 GiB      | 521 MiB          |
+| golang/go, time           | did not complete      | 23 s             |
+| Xe/x, peak heap           | 516 MiB               | about 165 MiB    |
+| Xe/x, time                | 14.7 s                | 1.3 s            |
+| 266 MB blob and one delta | both bodies in memory | 35 MiB peak heap |
+
+A second test reads every object back through a new `Storer` and verifies
+its hash. It passes for all 708,000 objects of golang/go. It also passes for a
+chain of 50 links, a chain of 197 links, and the 266 MB blob. Each case passes
+with the default memory bound, and again with every body sent to disk.
+
+The two writers store the same deltas. For Xe/x, both keep 12,016 deltas and
+both store 39 MiB.
+
+### Spill to disk by default?
+
+A run that sends every body to disk took 140 s, against 23 s. System time went
+from 5 s to 109 s. Most objects are a few kilobytes, so each one costs file
+system calls that are larger than the work. Each copy command in a delta also
+becomes one `pread`. The peak heap fell by only 33 MiB, because the 64 MiB
+budget already bounds the bodies in memory.
+
+## A bug that phase 1 found
+
+A stored delta chain of exactly 50 links did not read back. `deltaBase`
+refused depth 50, but depth 50 is the link that reaches the whole object. Git
+uses a default `pack.depth` of 50, so normal pushes make such chains. The
+writer on `main` has the same fault. The memory problem hid it, because
+golang/go never got far enough.
+
+A client can also send chains of up to 4095 links, and a read walks only 50.
+Two changes correct this:
+
+- A read now accepts a chain of exactly `maxDeltaDepth` links.
+- If a stored chain is already `maxDeltaDepth` links long, the writer stores
+  the next object whole. In a chain of 197 links, this stores 10 of 803 objects
+  whole.
+
+## Phase 2: make the pack index compact (done)
+
+After phase 1, the memory that remains grows with the number of objects, at
+about 390 bytes for each live object. For golang/go that is about 275 MiB.
+For a repository of 10 million objects, it is about 4 GB.
+
+| Part                           | Bytes per object | golang/go |
+| ------------------------------ | ---------------: | --------: |
+| `packIndex.entries` map        |        about 210 |   149 MiB |
+| `cueRecord` slices of the push |         about 70 |    48 MiB |
+| push scan index                |         about 50 |    35 MiB |
+| zstd history (fixed)           |                – |    64 MiB |
+
+The map is the largest part. Reads use it too: a clone or a fetch builds the
+same map for every object in the repository. A smaller map therefore helps
+both the push and the read path.
+
+### Design
+
+Replace `entries map[plumbing.Hash]packEntry` with a list of sorted tables.
+
+- A table holds the hashes of its objects as one `[]byte`, sorted, with
+  `hashSize` bytes for each hash.
+- A parallel slice holds a small fixed-size record for each object: the pack
+  number, the offset, the stored length, the raw size, the type, and the
+  codec.
+- The base of a delta is an index into the same table. A base in another
+  table goes in a small side map. The writer keeps a base and its delta in the
+  same container, so the side map is almost always empty.
+- A table has a slice of pack ids. Each record holds a `uint32` index into
+  that slice, and not a `string`.
+
+This takes about 50 bytes for each object, against about 210 bytes now.
+
+`packLookup` does a binary search in each table. The cold build makes one
+table from every `.cue`. Each container that a push registers adds one table.
+When there are more than 16 tables, the index merges them into one table, so
+a lookup never searches more than 16 tables.
+
+`deregister` removes a table that is still alone. For a table that a merge
+absorbed, it adds the pack id to a set of dead packs, and a lookup skips a
+record from a dead pack. `deregister` then needs only the pack id, so
+`packJob` no longer holds its `[]cueRecord` until the upload completes.
+
+`snapshotEntries` keeps its order, by pack and then by offset. It reads that
+order from the tables.
+
+`packEntry` stays as the type that `packLookup` returns. The lookup builds it
+from a record, so callers do not change.
+
+### Order of work
+
+1. Add the table type with lookup, merge, and dead packs. Give it
+   table-driven tests.
+2. Move `indexRecords`, `register`, `deregister`, `packLookup`, and
+   `snapshotEntries` to the tables.
+3. Change `packJob` and `deregister` to use the pack id only.
+4. Make the cold build parse each `.cue` into a table, and then release the
+   parsed records.
+5. Measure the push and a cold index build of golang/go again.
+
+### Results of phase 2
+
+The tables work as the design says, with two changes:
+
+- The iterator does not copy the entries. It keeps an 8-byte reference to each
+  record, and yields a hash only from the record that the lookup returns. This
+  removes the `seen` map, which cost more than 48 bytes for each object.
+- A snapshot shares the table list, the ids, and the dead set with the index,
+  and does not copy them. A lookup takes a snapshot, so a copy there cost a
+  clone of every pack id on every lookup.
+
+| Measurement (golang/go)          | Phase 1 | Phase 2 |
+| -------------------------------- | ------: | ------: |
+| Cold index build, live heap      | 225 MiB | 113 MiB |
+| Of which, the index itself       | 180 MiB |  40 MiB |
+| Push, peak heap                  | 521 MiB | 364 MiB |
+| Push, live heap after the upload | 274 MiB | 114 MiB |
+
+The other 73 MiB of the cold build is fixed. 45 MiB is the buffers of the
+`.cue` zstd decoder, and 28 MiB is the bodies that the S3 fake keeps.
+
+The round-trip test passes for all 708,000 objects of golang/go, and for every
+other case of phase 1. The race detector finds no race in the package.
+
+### Two changes for push time
+
+A CPU profile of the push showed that system calls took about 80% of the
+time. Two causes were in this package:
+
+- `packSegment` wrote to its file with no buffer. Each object cost at least one
+  `write` call, which was 14.7 s of a 26 s push. The segment now writes
+  through a 1 MiB buffer and counts its bytes, so `copyCompressed` needs no
+  `Seek`.
+- Each inflate read its section through a 32 KiB buffer, so a small object
+  still read 32 KiB. A section of 64 KiB or less is now read with one `ReadAt`
+  of its own length.
+
+The wall time did not change by a measurable amount, at 25 s to 28 s on a
+laptop. One `pread` for each inflate, about 1.4 million calls, now takes most
+of the time. See phase 3.
+
+## Phase 3: work to examine later
+
+- **Index size for very large repositories.** After phase 2, about 110 bytes
+  for each object remain during a push: the scan index and the tables. For 10 million objects that is about
+  1.1 GB. A table can live in a memory-mapped temp file, and then the kernel
+  can page it out.
+- **One `pread` for each inflate.** A memory map of the staged pack removes
+  these calls. The mapped pages count in the RSS of the process, but they are
+  file pages that the kernel can drop. A `pread` puts the same pages in the
+  page cache, and cgroup accounting counts them in both cases.
+- **The `.cue` zstd decoder.** It keeps about 45 MiB of buffers after its
+  first use. A lower decoder concurrency cuts that.
+- **The zstd encoder.** It keeps 64 MiB of history for each process.
+  `EncodeAll` inputs are at most `inMemoryCap` (1 MiB), except `.cue` blocks.
+  A 1 MiB window cuts that to about 8 MiB. This changes the compressed bytes,
+  so it needs its own measurement.
+- **Large bases in their own container.** An object larger than
+  `maxPackBytes` gets a container of its own. A delta against it lands in the
+  next container, so the writer stores that delta whole. This behavior is
+  older than this plan.