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.mdindex 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 therepository, like a push; housekeeping repacks them as it repacks the packs ofpushes.+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 updateThe combined update is made as the synthetic user `graft-batch` (name `Graft`,diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.mdindex 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 packwritten before the update. An operator who sets `core.fsync` in the `[git]`configuration overrides this for the helper processes too (the configurationof 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 limitationsdiff --git a/doc/graft/PLAN8.md b/doc/graft/PLAN8.mdindex 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 resolvecommit 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