Skip to content

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.md
index 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.md
index 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 the
request 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 attempts
packed 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 file
diff --git a/doc/graft/PLAN10.md b/doc/graft/PLAN10.md
index 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. When
every conflicting file has a landable verdict with its key, and the lane's classification of the
file 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; without
verify.enabled the members chain, one on the other's tip. With it a member lands only on a tree
that passed, so a member whose tree is not the verified one (the batch changed the tip under it) goes
back 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. UserLand
pre-resolves only them against the new tip, out of the lane, keeps every other verdict, and
enters 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's
re-land; a resolution with a model takes seconds to minutes. One shared pool would let a few
long 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 an
agent'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.md
index 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, and
never 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 not
resolve 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 it
discards, 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 change
and 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, and
the server resolves only that file, out of the lane, and enters the lane
again.
@@ -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 that
have 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 a
model for it. What a rule cannot resolve, or does not resolve in time, is handed back and resolved out of the lane as
described above. The lands on a hot file ride the same batches as the others, as they did in v0.2.0. The lane is
bounded: 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