Git designed for AI agents.
doc: PLAN9 section 14, decisions and amendments
Federico Eliafec68e1e67d3
diff --git a/doc/graft/PLAN9.md b/doc/graft/PLAN9.mdindex 0937a1a..77dd897 100644--- a/doc/graft/PLAN9.md+++ b/doc/graft/PLAN9.md@@ -595,5 +595,57 @@ and commit build (95 to 146 ms), stage 2.* `UserSquash` (seen during the audit, not p5w's code): when the merge fails withan error that is not a conflict, the error is dropped and the RPC votes andmigrates with an empty commit ID (`squash.go`, after `s.merge`). Reported to the- PM, not changed here.+ PM; fixed afterwards on the PM's decision (section 14).* `cmdCfg.worktreePath` stays: this plan does not touch the command factory.++## 14. Decisions and amendments after approval (recorded by p5w with the PM's decisions)++* **Q1 (custom hooks): both paths.** Custom hooks get the server's `core.fsync` and+ `core.fsyncMethod` (`GIT_CONFIG_*`, computed like the command factory: its+ defaults, then the administrator's `[git]` configuration), and a custom hook that+ runs with a quarantine as its object directory marks it+ (`quarantine.MarkUntrustedWriter`); the migration of a marked quarantine fsyncs its+ files in parallel first (`graft_quarantine_untrusted_migrations_total`). The mark+ is kept in process memory: custom hooks always run in the Gitaly process+ (`hook.NewManager` is built by `gitaly serve` only; `gitaly-hooks` forwards to the+ HookService), which an end-to-end test through `UserCommitFiles` with a hook that+ writes a zlib object with `cp` confirms. A marker file in the quarantine was not+ used: the hook itself could remove it. The environment golden of the hook tests+ includes the six variables (case B: Q1 added them).+* **Q2 (ownership): granted** for `internal/graft/changelog/log.go`,+ `internal/gitaly/hook/changeset_order.go`, the `recordChangesets` part of+ `referencetransaction.go`, `cmd/graft-bench`, and `internal/gitaly/hook/custom.go`+ for the two changes of Q1.+* **Q3 (G5): kept**, with the guarantee in LIMITATIONS.md in the PM's words: the+ objects of an update that fails after the migration remain unreferenced until+ housekeeping prunes them, they passed the pre-receive hook, and until pruned+ anyone with read access can read them by object ID.+* **Lost records are visible (binding).** A failed group write cannot fail the+ update (git committed it), so it is counted (`graft_changelog_records_lost_total`),+ logged with the references, and stated in LIMITATIONS.md as a limit of the off and+ shadow modes.+* **A failed append cuts its bytes off (amendment).** After a failed fsync the kernel+ may drop the dirty pages while the bytes still read back, so every failure after+ the write truncates the log to the old durable end; when the truncation fails too,+ the bytes are remembered as untrusted and never loaded, and the next append+ truncates them. A failed entry was never visible, so the next entry takes its+ sequence (the existing test that expected a skipped sequence changed with this+ contract).+* **Readers load under the lock file.** A reader that finds the log changed by+ another process loads it again under the log's lock file, after an fsync, so it+ waits for an append of that process and never loads bytes before their fsync.+* **`UserSquash` (binding).** Fixed in its own commit after a reproduction test+ (`4e8f423`), and shipped in v0.2.0.+* **WP94 order of links.** The first pass keeps the order of today within each+ directory (a pack's index after its data); a crash before each link, in a child+ process, leaves a prefix of the links that `git fsck` accepts.+* **WP95** is a source scan of the places that set `core.fsync`, `core.fsyncMethod`+ or use `WithoutObjectFsync`, instead of a run of every writing RPC: it fails on a+ new place, which must then be checked against the contract.+* **WP96 count** (diagnosis, before the window): one `UserCommitFiles` of one new+ file costs 12 git processes on an existing branch and 15 on a new one+ (`hash-object` 4, `rev-parse` 3 to 5, `for-each-ref` 1 to 2, and one each of+ `ls-tree`, `commit-tree`, `cat-file`, `update-ref`). The gate of stage 2 is decided+ with the numbers of the window.+* **Release.** v0.2.0 is main with phase 4b, the skew fix, its performance fix+ (`6aecff1`) and the `UserSquash` fix. The rest of this plan goes to v0.3.0.