Skip to content

Git designed for AI agents.

docs: where the Preparing phase of authoritative writes spends its time

Federico Elia09db8f2ef130
diff --git a/doc/graft/STORAGE.md b/doc/graft/STORAGE.md
index 86f6fe4..64a2a8b 100644
--- a/doc/graft/STORAGE.md
+++ b/doc/graft/STORAGE.md
@@ -823,6 +823,49 @@ show:
about 140 ms (SQLite) and 240 ms (Postgres) on a land of about 300 ms. A
catch-up check that finds the copy fresh costs well under 2 ms.
+### Where the Preparing phase spends its time
+
+Measured on 2026-10-20 with `graft_storage_preparing_step_seconds`, to decide
+whether a land should upload the pack it already wrote instead of building a
+second one.
+
+Setup:
+- the same machine;
+- 1-minute load below 2 at the start of every run, a fresh server per run;
+- authoritative mode, file bucket, gitai land mode, conflict rate 0, seed 1;
+- 1 writer × 20 changes and 10 writers × 5 changes, two runs per backend.
+
+The land transactions are `kind="update"`: 20 per run with 1 writer, 14 to 16
+with 10 writers, since a batch lands about 3.3 changes in one transaction. The
+commits onto the changes' own branches are `kind="create"`.
+
+Mean per land transaction, run by run:
+
+| step | SQLite (ms) | Postgres (ms) |
+|---|---:|---:|
+| record | 0.2 | 1.1–2.2 |
+| walk | 3.3–6.9 | 4.3–5.9 |
+| pack | 3.6–6.2 | 3.7–6.8 |
+| upload | 7.5–59.0 | 14.6–44.1 |
+
+The creates are in the same size class, for walk and pack alike, with larger
+uploads: 9–37 ms on SQLite and 18–130 ms on Postgres.
+
+What this shows:
+- **The upload dominates, in the mean and in the tail.** The p99 of a land's
+ upload reached 462 ms on SQLite. A commit's upload reached the top bucket,
+ about 2.2 s, in both single-writer Postgres runs.
+- **The upload is fsync latency.** The file bucket fsyncs every pack file and
+ its directories before `Put` returns. On this machine the WSL disk is shared
+ with the Postgres container, whose own fsyncs compete with the bucket's. This
+ is why the Postgres runs have the worst upload tails. An object-store bucket
+ behaves differently, and was not measured.
+- **Reusing the land's pack is not worth it.** Reuse could only remove the
+ `pack` step: 3.6–6.8 ms per land transaction, about 1–2 ms per land with
+ batching. That is before the cost of checking that the land's pack holds
+ every object the upload needs. The design required a 10 ms drop of the
+ Preparing mean on both backends, so the reuse was not built.
+
## Limits
- **Git still needs a local repository.** "Stateless" means that the local