Skip to content

Git designed for AI agents.

docs: the bounds of the inline resolution, tickets, and the gating of older graft-resolve

Federico Elia3aab7ad154b1
diff --git a/doc/graft/CONFIGURATION.md b/doc/graft/CONFIGURATION.md
index daed38e..ec0d8b9 100644
--- a/doc/graft/CONFIGURATION.md
+++ b/doc/graft/CONFIGURATION.md
@@ -202,7 +202,7 @@ cause.
| `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`. 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. |
+| `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 may lose to calls that fail is bounded once per batch attempt: a call that fails or is cut at `inline_timeout` is charged to the batch, and once the batch has lost `inline_timeout` the other members go out of the lane without a call (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. |
| `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/PLAN10.md b/doc/graft/PLAN10.md
index fde98c9..e4bd3f0 100644
--- a/doc/graft/PLAN10.md
+++ b/doc/graft/PLAN10.md
@@ -1295,14 +1295,23 @@ The resolution is bound to the files instead:
the lane never asks again for the life of the process). The split follows what the resolution is, not how long it
took: a model, a verification, a rule that does not end within `inline_timeout` (default 1 s) or one that cannot
resolve a file go out of the lane, to the path below. With the rules in the lane the bench has no hand-back, no
- ticket and one resolver call per resolution, and its numbers are v0.2.0's.
+ ticket and one resolver call per resolution, and its numbers are v0.2.0's. The lane is bounded: it 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 may
+ lose to calls that fail is bounded once per batch attempt (`landInlineBudget`: `inline_timeout` in all, not per
+ member). A land that the rules cannot resolve (the resolver refuses, or a file may not be sent) is resolved out of
+ the lane for the proposals and ends there, without a ticket: without a verification a model's resolution never
+ lands, so a ticket would protect nothing. The request announces no capability but `origin`, so that a
+ graft-resolve that gates the models on the capabilities (any since they were added) refuses to call one even if it
+ ignored `rules_only`; v0.2.0 has no gating and may.
2. **A queue for the lands that lose a round out of the lane.** A land that lost a round takes a ticket, first in
first out, on its files (per file; per branch when `verify.enabled`, since the tree that is verified is the
branch's), keeps it until it lands, its deadline ends or it fails, and is the only land of the branch that resolves
- them again; the others wait without calling the resolver, and the lane hands back any other land with a verdict on a
- ticketed file, so that the holder's verdict is the one that lands. Measured on the same bench with the rules out of
- the lane: 92 resolver calls, 8 hand-backs, 250 of 250. A land that waits past its deadline ends with the package
- ("the time ran out waiting for the other lands on the same files").
+ them again; the others wait without calling the resolver, and the lane hands back any land with a verdict made out
+ of the lane on a ticketed file, so that the holder's verdict is the one that lands. A ticket never stops the
+ rules in the lane: the inline attempt comes before the check of the tickets, and the land that waited for its turn
+ goes back to the lane, not to a new pre-resolution; a lane round does not count toward `resolve_rounds`. Measured
+ on the same bench with the rules out of the lane: 92 resolver calls, 8 hand-backs, 250 of 250. A land that waits
+ past its deadline ends with the package ("the time ran out waiting for the other lands on the same files").
3. resolve_rounds (default 32) is only a safety cap: the rounds of a land are bounded by its deadline, and the queue
makes it lose at most the rounds that a land which changes its files without a conflict makes it lose.
The limits, stated. The queue is in memory and per process, like the lanes: against another node of the same branch
diff --git a/doc/graft/RESOLVE.md b/doc/graft/RESOLVE.md
index bc45cf3..c0780fe 100644
--- a/doc/graft/RESOLVE.md
+++ b/doc/graft/RESOLVE.md
@@ -549,14 +549,21 @@ A round is lost when another land changed one of the files. The rules do not wai
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
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. A resolver that
- does not echo `rules_only` is an older one: its answer is dropped and the lane never asks again for the life of the
- server process.
-* **A queue for the rest.** A land that loses a round out of the lane (a model, or a verification, or a rule that
- takes more than `inline_timeout`) takes a ticket on its files, first in first out, and keeps it until it ends. It is
- the only land of the branch that resolves those files again; the others wait without calling the resolver, and the lane
- hands back any other land with a verdict on them. A land that waits past its deadline ends with the merge conflict and
- its package, its files `NOT_ATTEMPTED` with the reason `the time ran out waiting for the other lands on the same files`.
+ 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
+ not stop the rules; with it taken the member goes out of the lane), and a call that fails or is cut at `inline_timeout`
+ is charged to the batch attempt: once the batch has lost `inline_timeout` the other members go out of the lane without
+ a call, so a batch stalls once, not once per member. A land the rules cannot resolve (the resolver refuses) is
+ resolved out of the lane for the proposals and ends there, without a ticket (without a verification a model's
+ resolution never lands). A resolver that does not echo `rules_only` is an older one: its answer is dropped and the
+ lane never asks again for the life of the server process.
+* **A queue for the rest.** A land that loses a round out of the lane (a verification, or a rule that takes more than
+ `inline_timeout`, or a file that changed meanwhile) takes a ticket on its files, first in first out, and keeps it until
+ it ends. It is the only land of the branch that resolves those files again; the others wait without calling the
+ resolver, and the lane hands back any other land whose verdicts were made out of the lane. The rules in the lane do
+ not wait for a ticket, and a land that waited for its turn goes back to the lane. A land that waits past its
+ deadline ends with the merge conflict and its package, its files `NOT_ATTEMPTED` with the reason `the time ran out
+ waiting for the other lands on the same files`.
The tickets are per file, or per branch with `verify.enabled` (the tree that is verified is the branch's). They are in
the memory of the server process, like the lanes: with several nodes on one branch (authoritative storage) the lands
go on in rounds across nodes, without this order.
@@ -790,13 +797,15 @@ them. Cost: two model calls per region.
verify a model's resolution; upgrade the server". The rules are unaffected. A client of the protocol of your own that
sends no capabilities gets no model's resolution either.
* *An older `graft-resolve` and the inline resolution of the rules.* A server of this release asks `graft-resolve` for
- its rules only (`"rules_only": true`, see "Out of the lane") when the lane resolves a member inline. An older
- `graft-resolve` ignores the field, so it may call a model for that request: the lane gives the call `inline_timeout`
- (default `1s`) and drops the answer, which is not a rule's, whatever it is. The first lands that meet a conflict in the
- lane, at the same time, each pay such a call, at most `inline_timeout` of the lane each, until the first answer that
- does not echo `rules_only` makes the server stop asking, for the life of the process (`graft: the resolver did not
- honour a request for its rules only` in the log). After that the rules are resolved out of the lane, with the queue,
- as before this release. Set `inline_timeout = "0s"` to avoid even those calls with an older `graft-resolve`.
+ its rules only (`"rules_only": true`, see "Out of the lane") when the lane resolves a member inline, and announces
+ no capability but `origin`. A `graft-resolve` that gates the models on the capabilities (any since the capabilities
+ were added) refuses to call a model for that request, even if it ignores the field. The `graft-resolve` of v0.2.0 has
+ no gating: it ignores the field, so it may call a model, and the lane gives the call `inline_timeout` (default `1s`)
+ and drops the answer, which is not a rule's, whatever it is. A batch pays at most `inline_timeout` for such calls
+ (the lane's budget), and the first answer that does not echo `rules_only` makes the server stop asking, for the life
+ of the process (`graft: the resolver did not honour a request for its rules only` in the log). After that the rules
+ are resolved out of the lane, with the queue, as before this release. Set `inline_timeout = "0s"` to avoid even
+ those calls with the `graft-resolve` of v0.2.0.
Upgrade both in the same maintenance window anyway.