Skip to content

Git designed for AI agents.

doc: the publish modes and the pack of a lost batch attempt

Federico Elia9bf474279b0b
diff --git a/doc/graft/LAND-BATCHING.md b/doc/graft/LAND-BATCHING.md
index aa47f51..336926b 100644
--- a/doc/graft/LAND-BATCHING.md
+++ b/doc/graft/LAND-BATCHING.md
@@ -136,6 +136,13 @@ CAS*), and the branch does not move. Each published batch adds one pack to the
repository, like a push; housekeeping repacks them as it repacks the packs of
pushes.
+A land that is not batched writes the few objects of its change with the server's
+fsync configuration and publishes them as loose objects, without a pack: a pack
+would cost a process and as many fsyncs for so few objects, and under contention
+every attempt that loses the compare-and-swap would leave a pack in the repository.
+In both cases every object file of the quarantine is durable before the quarantine
+migration moves it.
+
### Hooks and identity of the combined update
The combined update is made as the synthetic user `graft-batch` (name `Graft`,
diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.md
index 6e13b31..e1ac8b1 100644
--- a/doc/graft/LIMITATIONS.md
+++ b/doc/graft/LIMITATIONS.md
@@ -280,14 +280,17 @@ commitment.
section 9.
3. Each published batch adds one small pack to the repository, as a push does.
Housekeeping repacks them like the packs of pushes, so busy branches make
- repacks more frequent.
+ repacks more frequent. A batch attempt that loses its compare-and-swap (to
+ another node or an external writer) also leaves its pack in the repository,
+ unreferenced, until housekeeping prunes it: at most one per lost batch attempt.
+ Unbatched lands publish loose objects and leave no pack.
4. The objects of a batch are written without fsync and made durable by the pack
written before the update. An operator who sets `core.fsync` in the `[git]`
configuration overrides this for the helper processes too (the configuration
of the administrator is applied last), which keeps the old per-object fsyncs.
-5. An unbatched land decides, rebases and publishes like a batch attempt (one range
- listing, the rebase engine, one pack), but it is still bounded by its own
- compare-and-swap retries under contention (`max_attempts`).
+5. An unbatched land decides and rebases like a batch attempt (one range listing and
+ the rebase engine) and publishes its objects loose, but it is still bounded by its
+ own compare-and-swap retries under contention (`max_attempts`).
## Phase 4a limitations
diff --git a/doc/graft/PLAN8.md b/doc/graft/PLAN8.md
index b8054a3..32e703c 100644
--- a/doc/graft/PLAN8.md
+++ b/doc/graft/PLAN8.md
@@ -565,6 +565,20 @@ the doc sections, all checked by Opus.
the committer applied); `localrepo/rebase_options_export.go` was deleted as dead.
* **Peel errors:** only `catfile.NotFoundError` is `InvalidArgument` ("cannot resolve
commit ID"); a failure of the object info process is `Internal`.
+* **Publish mode (after window 2):** window 2 showed that publishing every unbatched
+ attempt as a pack regresses contended unbatched lands: at 100 agents about 98% of
+ the ~6600 attempts lose the compare-and-swap, each left a migrated, unreferenced
+ pack (`pack-objects` 1 s → 1484 s, `update-ref` 56 s → 840 s, 120 packs against 4
+ at the end), and the off p99 went from 10-12 s to 34-35 s. A pack makes objects
+ durable cheaply only when it amortizes many of them. So the attempt has one mode
+ value, chosen by the caller: `landPublishPack` (batch attempts: the rebaser writes
+ without fsync, publish packs with fsync before the update) and `landPublishLoose`
+ (unbatched attempts: the rebaser writes with the server's fsync configuration,
+ nothing is packed, the migration moves the loose objects). No combination of
+ "no write-time fsync" with "loose migration" exists. Both keep the quarantine's
+ durability contract, stated in the code: every object file of a quarantine is
+ durable before the migration, which is not relied on to fsync it (p5w will make
+ the migration fsync only the directories).
* **G1:** closed by measurement (section 9).
* **Not in p4b (moved to p5w, PLAN9):** writing the pack straight into
`objects/pack` was rejected (it would make a rejected attempt's objects