Git designed for AI agents.
PLAN11 docs: exact intent confirmation, the fail-closed lookup
Federico Elia8a26fd43aa99
diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.mdindex 5696aff..32c420f 100644--- a/doc/graft/LIMITATIONS.md+++ b/doc/graft/LIMITATIONS.md@@ -197,8 +197,14 @@ Git hooks use private.- In the file changelog, every land update writes and fsyncs its intents(`graft/changelog.intents`) in the prepared phase, under the references'locks, and a land whose intents cannot be written fails. The intent of an- update that git never committed and whose change never landed again stays in- the file, one line of about 190 bytes per such update.+ update that git never committed stays in the file, one line of about 200+ bytes per such update.+- A land that diverges reads the land identities before it rebases or+ merges, and fails when it cannot: an error reading the changeset log or the+ identity index, or a timeout on their lock files, fails the land rather than+ risking a second land of the same change. This fail-closed behaviour is+ deliberate; the error is `Internal` in the file changelog and `Unavailable`+ when the storage core's database cannot be read.- In the file changelog, the land identity index (`graft/changelog.lands`)holds every land of the repository. The idle indexes of a process are keptin memory within 64 repositories and 256 MiB, least recently used droppeddiff --git a/doc/graft/PLAN11.md b/doc/graft/PLAN11.mdindex 67be339..98380f2 100644--- a/doc/graft/PLAN11.md+++ b/doc/graft/PLAN11.md@@ -138,27 +138,39 @@ change (and land it again if it was reverted). The hook therefore records the idof a land as intents in the prepared phase, before git may commit:* `graft/changelog.intents`, JSON lines- `{"ref":"<base64>","original":"...","landed":"...","head":N}`, appended under its- lock file and fsync'd (with the directory entries, once per process) before the- prepared phase returns. `head` is the last durable log sequence at that time. A- failure to record them aborts the transaction: the land fails instead of landing- without its identity. A torn line, left by a writer that crashed before its fsync and- whose update was therefore never committed, is cut off by the next writer.+ `{"ref":"<base64>","original":"...","landed":"...","invocation":"..."}`, appended+ under its lock file and fsync'd before the prepared phase returns, with the directory+ entries when the write created the file or is the first of the process to this file+ (device and inode: a repository created again at the same path has another file). The+ invocation identifies the update (the invocation of its reference transaction); the+ changelog entry that the update writes once committed carries it too+ (`land_invocation`). A failure to record the intents aborts the transaction: the+ land fails instead of landing without its identity. A torn line, left by a writer that+ crashed before its fsync and whose update was therefore never committed, is cut off by+ the next writer.* The lookup reads the intents too: it gives the land the changelog recorded first,- then the intents the changelog does not confirm (an intent with the recorded landed- commit) or supersede (a recorded land of the same commit at a later sequence than- its `head`). The land path counts an intent like a record, only when its landed- commit is reachable from the tip: the intent of an update that git never committed- (aborted after the prepared phase, an MVCC snapshot that lost its commit) answers- nothing. An answer from an intent has no changelog sequence; its detail says- "landed as <oid>, which the changelog does not record".-* The intents file is compacted, under its lock file, once it reaches 64 KiB and again- each time it doubled: the confirmed and superseded intents are dropped, the rest is- written to a new file, fsync'd and renamed over the old one, with the directory- fsync'd. The intents of updates that were never committed and whose change never- landed again stay; there is one line, about 190 bytes, per such update.+ then the intents of other landed commits. No intent is left out because a record came+ after it (review m1: an earlier update's entry can be written after a later update's+ intent, and the later entry lost). The land path counts an intent like a record, only+ when its landed commit is reachable from the tip, which proves the land by itself: the+ commit is the one that update would put on the branch, and only an update that puts+ that very object there makes it reachable. The update of an aborted land migrated its+ objects before it was prepared, so its commit exists, off the branch, and answers+ nothing (review m2); so does the intent of an MVCC snapshot that lost its commit. An+ answer from an intent has no changelog sequence; its detail says "landed as <oid>,+ which the changelog does not record".+* An intent goes once the changelog entry of its own update is durable: the index keeps+ the invocations of the entries it read, and a compaction drops the intents with those+ invocations, and only those. The intents file is compacted, under its lock file, from+ 64 KiB on, when at least half of its intents may go: the rest is written to a new file,+ fsync'd and renamed over the old one, with the directory fsync'd. The lookups compact,+ and so does the append: once the file doubled since the last compaction, the hook+ starts one after the update, outside the references' locks, so that the intents of+ lands that never look up (fast-forwards only) go too. The intents of updates that were+ never committed stay; there is one line, about 200 bytes, per such update.* The cost is one write and one fsync per land update in the prepared phase, under the- references' locks; the bench measures it.+ references' locks, serialized per repository by the intents' lock file, not shared+ with the changelog's group commit; the bench measures it.In the authoritative mode the database row and the reference change are one transaction,so there is no such window and no intents.