Git designed for AI agents.
docs: make the docs agree on the rules in the lane, the tickets and the metrics
Federico Eliae879d6900df1
diff --git a/doc/graft/CONFIGURATION.md b/doc/graft/CONFIGURATION.mdindex eca6a72..712eccf 100644--- a/doc/graft/CONFIGURATION.md+++ b/doc/graft/CONFIGURATION.md@@ -200,9 +200,9 @@ cause.| `check_concurrency` | int | `2` | Checks of agents' resolutions that run at once in the Gitaly process, across all its listeners (one resolver client is shared by them); each holds a request of up to 64 MiB. A check waits for a free slot within its deadline (`timeout`), and fails closed when it expires. The wait is in `graft_resolver_check_slot_wait_seconds`. || `verify_per_repository` | int | `1` | Verifications that run at once for one repository (of any resolution: a rule's, an agent's, a model's), inside `verify_concurrency`: every land of a busy branch builds a tree of its own to verify, and one repository must not take the whole pool. A land waits for its repository's turn first, holding nothing of the pool, within the land's deadline. **The cost, stated:** a resolution lands only on the tree that was verified, so a land whose branch moved after its tree was verified is verified again, and on a busy branch the lands take their turns one repository at a time; at the deadline a land ends with the package (a rule's files `NOT_ATTEMPTED` with the reason, a model's `PROPOSED`) and the agent lands again. Lands of rules are batched only when `verify.enabled` is not set. || `verify_concurrency` | int | `2` | Verifications that run at once in the Gitaly process (of any resolution: a rule's, an agent's, a model's), all out of the lane, in a pool of their own that exists whenever `verify.enabled` is set, with or without an AI resolver, as `verify.command` takes minutes. A verification waits for a free slot within the land's deadline. The wait is in `graft_resolver_verify_slot_wait_seconds`. |-| `resolve_concurrency` | int | `2` | Resolutions that run at once in the Gitaly process, in a pool apart from the checks', so that long resolutions never delay a check. A resolution waits for a free slot within the land's deadline (`timeout`), and fails closed when it expires. The wait is in `graft_resolver_resolve_slot_wait_seconds`. |-| `resolve_rounds` | int | `32` | Safety cap on the rounds of a land whose conflicting files keep changing while it is resolved out of the lane. The rounds are bounded by `timeout`; a land that loses a round waits for its turn on its files in a queue, so that it does not lose them one after the other (RESOLVE.md, "Out of the lane"), and the cap is not reached in practice. It is no contract. |-| `inline_timeout` | string (Go duration) | `"1s"` | Bound of the call with which the lane resolves a member's conflicting files itself, as the rules (trivial, union, rerere, a command that is a rule) and never a model: the request carries `rules_only` and announces no capability but `origin`. The lane never waits for a slot (the calls have a pool of their own; with it taken the member goes out of the lane), and the time it spends in inline calls is bounded once per batch attempt: all the time of every call, a successful one too, is charged to the batch, and once the batch has spent `inline_timeout` the other members go out of the lane without a call (fast rules, milliseconds, do not notice; a resolver that leaves child processes holding its output may keep the lane up to 2 s more, the kill delay). A member whose files the rules cannot resolve within it is resolved out of the lane, as any other. `"0s"` turns the inline resolution off. Never used with `verify.enabled`: every tree is then verified out of the lane. |+| `resolve_concurrency` | int | `2` | Resolutions that run at once in the Gitaly process, in a pool apart from the checks', so that long resolutions never delay a check. A resolution waits for a free slot within the land's deadline (`timeout`), and fails closed when it expires. The wait is in `graft_resolver_resolve_slot_wait_seconds`. The lane's inline calls (`inline_timeout`) have a pool of their own, of at least 8 slots, which the lane never waits for. |+| `resolve_rounds` | int | `32` | Safety cap on the rounds of a land whose conflicting files keep changing while it is resolved out of the lane. The rounds are bounded by `timeout`; a land that loses a round waits for its turn on its files in a queue, so that it does not lose them one after the other (RESOLVE.md, "Out of the lane"), and the cap is not reached in practice. A round that enters the lane without a pre-resolution (the first, and the ones after a wait for a turn; at most 4) does not count. It is no contract. |+| `inline_timeout` | string (Go duration) | `"1s"` | Bound of the call with which the lane resolves a member's conflicting files itself, as the rules (trivial, union, rerere, a command that is a rule) and never a model: the request carries `rules_only` and announces no capability but `origin`. The lane never waits for a slot (the calls have a pool of their own; with it taken the member goes out of the lane), and the time it spends in inline calls is bounded once per batch attempt: all the time of every call, a successful one too, is charged to the batch, and once the batch has spent `inline_timeout` the other members go out of the lane without a call (fast rules, milliseconds, do not notice; a resolver that leaves child processes holding its output may keep the lane up to 2 s more, the kill delay). A member whose files the rules cannot resolve within it is resolved out of the lane, as any other. `"0s"` turns the inline resolution off; a negative or invalid value is a configuration error. Never used with `verify.enabled`: every tree is then verified out of the lane. || `paths_allow` | array of strings | empty (every path) | Globs of paths that may be sent to the resolver, with the syntax of policy refs. || `paths_deny` | array of strings | empty | Globs of paths that are never sent. Deny wins over allow. || `actors` | array of strings | empty (every caller that may land) | Globs of the identities that may request resolution: agent names, or `shared` for the shared token. Without `[[graft.agent]]` no caller has an identity, so a non-empty list admits nobody (the server warns at startup). |diff --git a/doc/graft/LAND-BATCHING.md b/doc/graft/LAND-BATCHING.mdindex c54ed70..f4ae834 100644--- a/doc/graft/LAND-BATCHING.md+++ b/doc/graft/LAND-BATCHING.md@@ -78,7 +78,9 @@ One batch attempt:`not_ancestor` error.- A merge conflict fails only that request with `merge_conflict`. When therequest sets `resolve_conflicts` and the resolver is enabled, the conflict is- resolved first (see [RESOLVE.md](RESOLVE.md)).+ resolved first: by the lane itself for what the rules resolve within `inline_timeout`+ (default `1s`), and otherwise out of the lane, before the request enters it again (see+ [RESOLVE.md](RESOLVE.md), "Out of the lane").- A request whose outcome is final before the CAS (see *Early completion*)is answered at once.3. Publishes the final running tip with one CAS from the original tip. The@@ -410,7 +412,13 @@ The batch executor (`internal/gitaly/service/operations`) defines:- `graft_land_batch_packed_objects_total` (counter): objects that attemptspacked before their update.- `graft_land_batch_members_total{outcome}` (counter): requests by outcome, with- the outcomes `landed`, `already_landed`, `conflict`, `denied` and `error`.+ the outcomes `landed`, `already_landed`, `conflict`, `denied`, `error` and+ `needs_resolution` (the lane handed the request back to be resolved out of the lane, or to+ wait for its turn on its files; not a failure: a land that loses k rounds counts k of these).+- `graft_land_ticket_wait_seconds` (histogram): time a land that lost a round of its conflict+ resolution waited for its turn on its files ([RESOLVE.md](RESOLVE.md), "Out of the lane").+- `graft_land_resolution_rounds` (histogram): rounds (resolve, then the lane) a land with+ conflicts needed.The hooks (`internal/gitaly/hook`) define `graft_land_intents_seconds`(histogram): the land intents of one prepared reference transaction in the filediff --git a/doc/graft/PLAN10.md b/doc/graft/PLAN10.mdindex 5764113..8616c96 100644--- a/doc/graft/PLAN10.md+++ b/doc/graft/PLAN10.md@@ -1271,12 +1271,12 @@ The resolution is bound to the files instead:* **Landable: applied in the lane, file by file.** The lane merges its own tip and the change. Whenevery conflicting file has a landable verdict with its key, and the lane's classification of thefile agrees, the lane writes the verdicts into the merge commit and runs no command (15.9); the- resolver is not called. In a batch, a member's verdicts hold whenever their keys match; without+ lane does not call the resolver for it, except for the rules it resolves inline (below). In a batch, a member's verdicts hold whenever their keys match; withoutverify.enabled the members chain, one on the other's tip. With it a member lands only on a treethat passed, so a member whose tree is not the verified one (the batch changed the tip under it) goesback out to be verified, and lands alone.* **Needs resolution.** When a conflicting file has no verdict with its key (it is new, or a side- changed), the lane returns the attempt with those files, without resolving. UserLand+ changed), the lane tries the rules inline (below) and returns the attempt with the files they did not resolve. UserLandpre-resolves only them against the new tip, out of the lane, keeps every other verdict, andenters the lane again. A tip that moves on unrelated files costs no resolver call at all.* **Progress, and what it took.** A round is lost when the lane found a file whose sides changed, that is when@@ -1381,7 +1381,8 @@ The resolution is bound to the files instead:resolve_concurrency (new, default 2) the resolutions. A check is short and gates an agent'sre-land; a resolution with a model takes seconds to minutes. One shared pool would let a fewlong resolutions starve the checks, and fairness inside one pool needs a scheduler for no gain- over two plain semaphores; the memory bound of the process is the sum of the two pools' requests.+ over two plain semaphores; the memory bound of the process is the sum of the two pools' requests. The lane's inline calls (the rules in the+ lane, below) have a third pool, of at least 8 slots, which the lane never waits for.Each request waits for its slot within the resolver's timeout and fails closed when it expires.* **Nothing is verified in the lane.** Every verification, of a rule's resolution, a model's or anagent's, runs out of the lane, on one mechanism (15.9); the lane compares tree object IDs.diff --git a/doc/graft/RESOLVE.md b/doc/graft/RESOLVE.mdindex a24310e..e1a5fe9 100644--- a/doc/graft/RESOLVE.md+++ b/doc/graft/RESOLVE.md@@ -252,7 +252,9 @@ Request (server to resolver):older server, and `graft-resolve` gives it no model's resolution (see "Version skew" below).- `rules_only` (additive, optional) asks the resolver to run only its rules, the strategies whose answers are a rule's, andnever to call a model: the lane of the server sends it when it resolves a member inline (see "Out of the lane"). A- resolver of this release that honours it says so with `"rules_only": true` in its response; what the rules do not+ resolver of this release that honours it says so with `"rules_only": true` in its response; the request then+ announces no capability but `origin`, so that a `graft-resolve` that gates the models on the capabilities refuses a+ model even if it ignored the field; what the rules do notresolve is left unresolved, as a failure of the chain. A server that gets no echo is talking to an older resolver,whose answer it drops, and it never asks again for the life of the process.- `ours` is the current branch tip side. `theirs` is the change being landed.@@ -524,9 +526,10 @@ Every resolution carries its trailers, so it can be found and undone:## Out of the lane-The server calls the resolver before a land enters its branch's lane, never-while the lane is held, so a resolution that takes minutes does not hold the-branch for the other lands:+A resolution that takes minutes must not hold the branch's lane, so the server calls the resolver before a land+enters the lane, never while the lane is held for long. The one exception is the rules, which the lane resolves+itself within `inline_timeout` (default `1s`), as v0.2.0 did ("Rules in the lane" below). With it on (the default,+without `verify.enabled`) a land enters the lane first, and the steps below are for what the rules did not resolve:1. The server merges the branch's current tip and the change in a quarantine itdiscards, and resolves the conflicting files there: the policy first, the@@ -538,8 +541,8 @@ branch for the other lands:are kept.3. A landable answer enters the lane, which merges its own tip and the changeand writes the merge commit when every conflicting file has an answer with- its key; the resolver is not called. A tip that moved on other files costs- nothing. When a file changed (or is new), the lane hands the land back, and+ its key; the lane calls the resolver for no model, and for a rule only inline ("Rules in the lane" below). A tip+ that moved on other files costs nothing. When a file changed (or is new), the lane hands the land back, andthe server resolves only that file, out of the lane, and enters the laneagain.@@ -547,7 +550,8 @@ A round is lost when another land changed one of the files. The rules do not wai* **Rules in the lane.** Without `verify.enabled`, a land enters the lane first, and the lane resolves the files thathave no verdict itself, as the rules (trivial, union, rerere, a command that is a rule), within `inline_timeout`- (default `1s`; `0s` turns it off). It sends the request with `"rules_only": true`, and `graft-resolve` never calls a+ (default `1s`; `0s` turns it off). The policy is checked first, as out of the lane: an agent that may not update the+ branch gets nothing resolved. It sends the request with `"rules_only": true`, and `graft-resolve` never calls amodel for it. What a rule cannot resolve, or does not resolve in time, is handed back and resolved out of the lane asdescribed above. The lands on a hot file ride the same batches as the others, as they did in v0.2.0. The lane isbounded: it never waits for a slot (the calls have a pool of their own, so a model that holds the resolve slots does@@ -736,7 +740,8 @@ origin = "model" # its files are proposals, and land only if verify.command pa````origin` is `"rule"` (the default) or `"model"`. A model command's answers are-not recorded by `rerere`.+not recorded by `rerere`, and the command is not run for a request for the rules only (`"rules_only": true`, "Out of+the lane"), which is the request of the lane's inline resolution.**The agreement gate: `agree_with`.** The `llm` strategy alone produces a proposal that lands only if `verify.command`passes on the exact tree. An operator who wants model resolutions to land without an agent in the loop gets the best