@tobi-or-not/quorum 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/fingerprint.d.ts +8 -5
  3. package/dist/bench/fingerprint.js +28 -9
  4. package/dist/bench/records.d.ts +168 -0
  5. package/dist/bench/records.js +106 -1
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +30 -4
  8. package/dist/cli/bench.d.ts +11 -4
  9. package/dist/cli/bench.js +34 -17
  10. package/dist/cli/bin.js +2 -2
  11. package/dist/cli/io.d.ts +5 -0
  12. package/dist/cli/main.d.ts +67 -24
  13. package/dist/cli/main.js +288 -59
  14. package/dist/cli/print-config.d.ts +8 -6
  15. package/dist/cli/print-config.js +26 -8
  16. package/dist/cli/render.d.ts +9 -3
  17. package/dist/cli/render.js +43 -2
  18. package/dist/config/claude-code.d.ts +2 -6
  19. package/dist/config/claude-code.js +6 -44
  20. package/dist/config/command.d.ts +10 -0
  21. package/dist/config/command.js +47 -0
  22. package/dist/config/env.d.ts +32 -19
  23. package/dist/config/env.js +95 -32
  24. package/dist/config/from-config.js +21 -3
  25. package/dist/config/resolve.d.ts +13 -1
  26. package/dist/config/resolve.js +27 -1
  27. package/dist/config/schema.d.ts +152 -5
  28. package/dist/config/schema.js +156 -12
  29. package/dist/core/clock.d.ts +17 -0
  30. package/dist/core/clock.js +14 -0
  31. package/dist/core/coverage.d.ts +74 -0
  32. package/dist/core/coverage.js +221 -0
  33. package/dist/core/diff.d.ts +101 -0
  34. package/dist/core/diff.js +178 -35
  35. package/dist/core/errors.d.ts +12 -3
  36. package/dist/core/errors.js +21 -2
  37. package/dist/core/estimate.d.ts +45 -0
  38. package/dist/core/estimate.js +188 -0
  39. package/dist/core/exclude.d.ts +42 -0
  40. package/dist/core/exclude.js +189 -0
  41. package/dist/core/flags.d.ts +14 -1
  42. package/dist/core/flags.js +56 -0
  43. package/dist/core/inputs.d.ts +38 -0
  44. package/dist/core/inputs.js +228 -0
  45. package/dist/core/limits.d.ts +83 -0
  46. package/dist/core/limits.js +169 -0
  47. package/dist/core/output.d.ts +3 -2
  48. package/dist/core/output.js +3 -2
  49. package/dist/core/parts.d.ts +146 -0
  50. package/dist/core/parts.js +388 -0
  51. package/dist/core/ports.d.ts +67 -2
  52. package/dist/core/ports.js +36 -1
  53. package/dist/core/prompts.d.ts +22 -3
  54. package/dist/core/prompts.js +43 -7
  55. package/dist/core/quorum.d.ts +26 -8
  56. package/dist/core/quorum.js +310 -73
  57. package/dist/core/retry.d.ts +36 -0
  58. package/dist/core/retry.js +46 -0
  59. package/dist/core/secrets.d.ts +98 -0
  60. package/dist/core/secrets.js +507 -0
  61. package/dist/core/stages/context.d.ts +131 -23
  62. package/dist/core/stages/context.js +331 -46
  63. package/dist/core/stages/panel.d.ts +13 -6
  64. package/dist/core/stages/panel.js +79 -19
  65. package/dist/core/stages/research.d.ts +110 -25
  66. package/dist/core/stages/research.js +338 -44
  67. package/dist/core/tokens.d.ts +31 -0
  68. package/dist/core/tokens.js +81 -0
  69. package/dist/core/types.d.ts +280 -25
  70. package/dist/core/verify.d.ts +6 -0
  71. package/dist/core/verify.js +6 -3
  72. package/dist/git/run.d.ts +223 -0
  73. package/dist/git/run.js +608 -0
  74. package/dist/git/tree.d.ts +43 -0
  75. package/dist/git/tree.js +171 -0
  76. package/dist/index.d.ts +26 -2
  77. package/dist/index.js +34 -2
  78. package/dist/providers/anthropic.d.ts +3 -1
  79. package/dist/providers/anthropic.js +10 -3
  80. package/dist/providers/claude-code.d.ts +56 -11
  81. package/dist/providers/claude-code.js +70 -25
  82. package/dist/providers/gemini.d.ts +5 -1
  83. package/dist/providers/gemini.js +65 -11
  84. package/dist/providers/http.d.ts +49 -4
  85. package/dist/providers/http.js +155 -14
  86. package/dist/providers/ollama.d.ts +4 -1
  87. package/dist/providers/ollama.js +13 -5
  88. package/dist/providers/openai-compatible.d.ts +4 -1
  89. package/dist/providers/openai-compatible.js +13 -5
  90. package/dist/providers/options.d.ts +12 -3
  91. package/dist/providers/options.js +30 -10
  92. package/dist/providers/size.d.ts +19 -15
  93. package/dist/providers/size.js +33 -73
  94. package/dist/sources/added.d.ts +49 -0
  95. package/dist/sources/added.js +134 -0
  96. package/dist/sources/diff.d.ts +13 -0
  97. package/dist/sources/diff.js +63 -0
  98. package/dist/sources/local.d.ts +41 -0
  99. package/dist/sources/local.js +251 -0
  100. package/dist/sources/paths.d.ts +45 -0
  101. package/dist/sources/paths.js +230 -0
  102. package/dist/sources/range.d.ts +21 -0
  103. package/dist/sources/range.js +75 -0
  104. package/dist/sources/read.d.ts +69 -0
  105. package/dist/sources/read.js +37 -0
  106. package/dist/sources/repository.d.ts +9 -0
  107. package/dist/sources/repository.js +28 -0
  108. package/dist/sources/skips.d.ts +49 -0
  109. package/dist/sources/skips.js +126 -0
  110. package/package.json +1 -1
  111. package/schema/quorum.schema.json +49 -1
@@ -11,8 +11,14 @@ export interface PanelOutcome {
11
11
  }
12
12
  /**
13
13
  * The panel stage of one profile: every finding goes to every lens, each vote to the lens's own
14
- * provider, and the quorum verdict is computed in code. Each voter receives the diff section of the
15
- * file its finding cites.
14
+ * provider, and the quorum verdict is computed in code. A vote's context is the diff section of the
15
+ * file its finding cites, the whole diff when the file has no section of its own. It is partial only
16
+ * for a voter that states a room (`Provider.room`) the section does not fit: that voter receives the
17
+ * section's header and the hunks nearest the cited line that fit its room, the cited hunk first (see
18
+ * `nearestHunks`), and its diff block says so. A voter that states no room, or whose room holds the
19
+ * section, receives the section as before, and so does one whose room does not hold the cited hunk
20
+ * alone, which its provider then refuses as too large. The context is chosen when the vote's request
21
+ * is built, inside the vote's slot.
16
22
  *
17
23
  * A voter never sees the other votes or their reasoning - independence is the point, not an
18
24
  * oversight. Letting verifiers see each other's reasoning measurably converges results toward
@@ -21,10 +27,11 @@ export interface PanelOutcome {
21
27
  * self-reported confidence gets to override: with the security profile, unanimous 3/3 is a ceiling
22
28
  * of 'high', a 2/3 split is capped at 'medium' no matter how certain any one voter sounded.
23
29
  *
24
- * A failed vote counts as a reject and is recorded with its error, never as a crash, but a vote cut
25
- * by the review's abort is not a failed vote: it rejects the panel with the abort's reason at once,
26
- * without waiting for the votes still in flight. A vote request its provider refused as too large
27
- * is a failed vote that also records a `request-too-large` gap. Each vote emits a `vote` event.
30
+ * A failed vote counts as a reject and is recorded with its error and its failure, never as a crash,
31
+ * but a vote cut by the review's abort is not a failed vote: it rejects the panel with the abort's
32
+ * reason at once, without waiting for the votes still in flight. A vote request its provider refused
33
+ * as too large is a failed vote that also records a `request-too-large` gap. Each vote emits a `vote`
34
+ * event.
28
35
  * Once a finding's votes are in, its verdict emits a `verdict` event, then its gaps are reported by
29
36
  * `incomplete` events: one `request-too-large` gap when any vote request was refused, and a
30
37
  * `vote-failed` gap when a kept verdict's failed votes leave a higher level undecided (ADR-0012).
@@ -1,12 +1,21 @@
1
- import { diffSectionFor } from "../diff.js";
1
+ import { diffSectionFor, hunksOf, sectionFor } from "../diff.js";
2
+ import { isLimit } from "../limits.js";
2
3
  import { parseVoteReply } from "../output.js";
4
+ import { nearestHunks } from "../parts.js";
3
5
  import { confidenceFor, undecidedLevel, verdictStatus } from "../policy.js";
4
6
  import { voteRequest } from "../prompts.js";
5
- import { callProvider, isTooLarge, refusalMessage } from "./context.js";
7
+ import { tokenBound } from "../tokens.js";
8
+ import { callProvider, isTooLarge, providerFailure, refusalMessage, roomOf } from "./context.js";
6
9
  /**
7
10
  * The panel stage of one profile: every finding goes to every lens, each vote to the lens's own
8
- * provider, and the quorum verdict is computed in code. Each voter receives the diff section of the
9
- * file its finding cites.
11
+ * provider, and the quorum verdict is computed in code. A vote's context is the diff section of the
12
+ * file its finding cites, the whole diff when the file has no section of its own. It is partial only
13
+ * for a voter that states a room (`Provider.room`) the section does not fit: that voter receives the
14
+ * section's header and the hunks nearest the cited line that fit its room, the cited hunk first (see
15
+ * `nearestHunks`), and its diff block says so. A voter that states no room, or whose room holds the
16
+ * section, receives the section as before, and so does one whose room does not hold the cited hunk
17
+ * alone, which its provider then refuses as too large. The context is chosen when the vote's request
18
+ * is built, inside the vote's slot.
10
19
  *
11
20
  * A voter never sees the other votes or their reasoning - independence is the point, not an
12
21
  * oversight. Letting verifiers see each other's reasoning measurably converges results toward
@@ -15,16 +24,20 @@ import { callProvider, isTooLarge, refusalMessage } from "./context.js";
15
24
  * self-reported confidence gets to override: with the security profile, unanimous 3/3 is a ceiling
16
25
  * of 'high', a 2/3 split is capped at 'medium' no matter how certain any one voter sounded.
17
26
  *
18
- * A failed vote counts as a reject and is recorded with its error, never as a crash, but a vote cut
19
- * by the review's abort is not a failed vote: it rejects the panel with the abort's reason at once,
20
- * without waiting for the votes still in flight. A vote request its provider refused as too large
21
- * is a failed vote that also records a `request-too-large` gap. Each vote emits a `vote` event.
27
+ * A failed vote counts as a reject and is recorded with its error and its failure, never as a crash,
28
+ * but a vote cut by the review's abort is not a failed vote: it rejects the panel with the abort's
29
+ * reason at once, without waiting for the votes still in flight. A vote request its provider refused
30
+ * as too large is a failed vote that also records a `request-too-large` gap. Each vote emits a `vote`
31
+ * event.
22
32
  * Once a finding's votes are in, its verdict emits a `verdict` event, then its gaps are reported by
23
33
  * `incomplete` events: one `request-too-large` gap when any vote request was refused, and a
24
34
  * `vote-failed` gap when a kept verdict's failed votes leave a higher level undecided (ADR-0012).
25
35
  */
26
36
  export async function panel(ctx, run, findings, sections, diff) {
27
- const judged = await Promise.all(findings.map(finding => judge(ctx, run, finding, diffSectionFor(sections, finding.file, diff))));
37
+ const judged = await Promise.all(findings.map(finding => judge(ctx, run, finding, {
38
+ text: diffSectionFor(sections, finding.file, diff),
39
+ sections,
40
+ })));
28
41
  const outcome = {
29
42
  kept: [],
30
43
  discarded: [],
@@ -37,8 +50,8 @@ export async function panel(ctx, run, findings, sections, diff) {
37
50
  }
38
51
  return outcome;
39
52
  }
40
- async function judge(ctx, run, finding, diffContext) {
41
- const casts = await Promise.all(run.lenses.map(lens => castVote(ctx, run, finding, lens, diffContext)));
53
+ async function judge(ctx, run, finding, context) {
54
+ const casts = await Promise.all(run.lenses.map(lens => castVote(ctx, run, finding, lens, context)));
42
55
  const votes = casts.map(({ lensVote }) => lensVote);
43
56
  const refusals = casts.flatMap(({ refusal }) => refusal === undefined
44
57
  ? []
@@ -79,21 +92,26 @@ async function judge(ctx, run, finding, diffContext) {
79
92
  /**
80
93
  * One lens's vote on one finding, from the lens's own provider. A failed call or an unusable reply
81
94
  * is a vote of null with its error: the message of an `Error`, the text of anything else thrown.
82
- * A request its provider refused as too large is that failed vote too, and carries the refusal's
83
- * message besides, for the finding's `request-too-large` gap. Once the review is aborted, the vote
84
- * rethrows the abort's reason instead, whatever the call raised, so an aborted review never
85
- * resolves with a finding the abort left unreviewed. The `vote` event is emitted after the vote's
86
- * own `try`, so a sink that throws on it is never recorded as a failed vote.
95
+ * It also records its failure: `voteFailureOf` the error for a failed call (a call the token cap or the
96
+ * review's deadline stopped is a failed vote of kind `token-cap` or `review-deadline`), `unusable-reply`
97
+ * for a reply that came back and could not be read as a vote; a cast vote's failure is null. A request its provider refused as too large is
98
+ * that failed vote too, and carries the refusal's message besides, for the finding's `request-too-large`
99
+ * gap. Once the review is aborted, the vote rethrows the abort's reason instead, whatever the call
100
+ * raised, so an aborted review never resolves with a finding the abort left unreviewed. The `vote` event
101
+ * is emitted after the vote's own `try`, so a sink that throws on it is never recorded as a failed vote.
87
102
  */
88
- async function castVote(ctx, run, finding, lens, diffContext) {
103
+ async function castVote(ctx, run, finding, lens, context) {
89
104
  let lensVote;
90
105
  let refusal;
106
+ let replied = false;
91
107
  try {
92
- const text = await callProvider(ctx, { profile: run.id, role: 'vote', lens: lens.id }, lens, () => voteRequest(lens.instructions, finding, diffContext, run.guidelines));
108
+ const text = await callProvider(ctx, { profile: run.id, role: 'vote', lens: lens.id }, lens, () => requestFor(run, finding, lens, context));
109
+ replied = true;
93
110
  lensVote = {
94
111
  angle: lens.id,
95
112
  vote: parseVoteReply(text),
96
113
  error: null,
114
+ failure: null,
97
115
  };
98
116
  }
99
117
  catch (error) {
@@ -105,11 +123,14 @@ async function castVote(ctx, run, finding, lens, diffContext) {
105
123
  error: error instanceof Error
106
124
  ? error.message
107
125
  : String(error),
126
+ failure: replied
127
+ ? { kind: 'unusable-reply' }
128
+ : voteFailureOf(error),
108
129
  };
109
130
  if (isTooLarge(error))
110
131
  refusal = refusalMessage(error);
111
132
  }
112
- const { error } = lensVote;
133
+ const { error, failure } = lensVote;
113
134
  ctx.emit({
114
135
  type: 'vote',
115
136
  profile: run.id,
@@ -119,11 +140,50 @@ async function castVote(ctx, run, finding, lens, diffContext) {
119
140
  ...(error === null
120
141
  ? {}
121
142
  : { error }),
143
+ ...(failure === null
144
+ ? {}
145
+ : { failure }),
122
146
  });
123
147
  return refusal === undefined
124
148
  ? { lensVote }
125
149
  : { lensVote, refusal };
126
150
  }
151
+ /**
152
+ * The request of one vote. The finding's cited file's section is its context, as `voteRequest` takes it,
153
+ * unless the lens's voter states a room the section does not fit: its room for the request with an empty
154
+ * diff block, which text added to the block lowers by exactly its `tokenBound`, is below the section's.
155
+ * The context is then the section's header and the hunks nearest the cited line that fit the room of the
156
+ * request that describes them (see `nearestHunks`), when the cited hunk fits alone. A voter that states no
157
+ * room has no request built to ask. `undefined` from `nearestHunks`, a cited line no hunk holds or a cited
158
+ * hunk that does not fit alone, sends the whole context, which the provider refuses as too large if it is.
159
+ */
160
+ function requestFor(run, finding, lens, context) {
161
+ const nearest = lens.room === undefined
162
+ ? undefined
163
+ : nearestContext(run, finding, lens, context.sections);
164
+ return nearest === undefined
165
+ ? voteRequest(lens.instructions, finding, context.text, run.guidelines)
166
+ : voteRequest(lens.instructions, finding, nearest, run.guidelines, true);
167
+ }
168
+ /** The partial context of a voter that states a room, or undefined when the whole section fits, or nothing of it does. */
169
+ function nearestContext(run, finding, lens, sections) {
170
+ const section = sectionFor(sections, finding.file);
171
+ if (section === undefined)
172
+ return undefined;
173
+ const room = roomOf(lens, voteRequest(lens.instructions, finding, '', run.guidelines));
174
+ if (room === undefined || tokenBound(section.text) <= room)
175
+ return undefined;
176
+ const partialRoom = roomOf(lens, voteRequest(lens.instructions, finding, '', run.guidelines, true));
177
+ return partialRoom === undefined
178
+ ? undefined
179
+ : nearestHunks(section.text, hunksOf(sections, section.path, section.text), finding.line, partialRoom);
180
+ }
181
+ /** What a call that failed says of itself as a vote's failure: the limit that stopped it, else what `providerFailure` reads, else `unknown`. */
182
+ function voteFailureOf(error) {
183
+ if (isLimit(error))
184
+ return { kind: error.limit };
185
+ return providerFailure(error) ?? { kind: 'unknown' };
186
+ }
127
187
  /**
128
188
  * The gap a finding leaves when its provider refused some of its vote requests as too large. The file
129
189
  * name is JSON-quoted, as in `voteFailed`; the detail names the first refusal in lens order.
@@ -1,3 +1,5 @@
1
+ import type { DiffSection } from '../diff.ts';
2
+ import type { Packing, PartOutcome } from '../parts.ts';
1
3
  import type { Finding, IncompleteEntry } from '../types.ts';
2
4
  import type { ProfileRun, RunContext } from './context.ts';
3
5
  /** How many reported findings a research reply may send to the panel; the rest is reported as incomplete. */
@@ -9,8 +11,15 @@ export interface ResearchOutcome {
9
11
  * code outside the diff, or names no file). An unreadable finding is reported in `incomplete` only.
10
12
  */
11
13
  invalid: string[];
12
- /** What the run could not review: findings the harness could not read, findings beyond the cap, a reply whose findings were all unusable, or a research request refused as too large. */
14
+ /** What the run could not review: findings the harness could not read, findings beyond the cap, a reply whose findings were all unusable, research requests refused as too large, or an advisory profile's research that failed. */
13
15
  incomplete: IncompleteEntry[];
16
+ /**
17
+ * What became of each research part, in the parts' order: `reviewed` when its reply was a valid findings
18
+ * envelope, the limit's name when the token cap or the deadline stopped it (its gap is written once the
19
+ * profile's panel has run, with the votes the limit stopped), else why it was not read. One entry for a
20
+ * research of one request, none when no part holds any of the diff.
21
+ */
22
+ parts: PartOutcome[];
14
23
  }
15
24
  /**
16
25
  * The id of a finding, stable across runs: the first 12 hex characters of SHA-256 over the JSON
@@ -20,34 +29,110 @@ export interface ResearchOutcome {
20
29
  */
21
30
  export declare function findingId(profile: string, file: string, line: number, category: string): string;
22
31
  /**
23
- * Turn a research reply into what the panel receives. The reply is parsed strictly (a malformed
24
- * envelope, or one with a key other than `findings`, throws, so it never reads as "no findings"),
25
- * only the first `maxFindings` findings it lists are read and checked against the diff (the work
26
- * spent on a reply built to flood the run stays bounded, whatever the entries hold), and nothing
27
- * the harness read is dropped silently: a finding that does not match the reply schema (what
28
- * planted text that closes a string early leaves behind), findings beyond the cap, and a reply
29
- * whose findings were all unusable, are recorded as incomplete, which fails the run (ADR-0012).
30
- * A finding that cites code outside the diff is only dropped with its reason: it was read, and
31
- * it is wrong. `invalid` holds only the reasons of the findings the check against the diff
32
- * dropped, so an unreadable finding is reported once, in `incomplete`. Every finding it keeps is
33
- * named by `findingId` and tagged with `profile`, and every incomplete entry it records is tagged
34
- * with `profile` too.
32
+ * How one profile's research goes: the sections of the filtered diff, and how they are packed. No packing
33
+ * is one request holding the whole diff, as it always was. A packing is the parts the research is sent in,
34
+ * and `listed` is the change's files every part's request names.
35
+ */
36
+ export interface ResearchPlan {
37
+ readonly sections: readonly DiffSection[];
38
+ readonly packing?: Packing;
39
+ /** The files the parts' requests name; set with `packing`. */
40
+ readonly listed?: ListedFiles;
41
+ }
42
+ /** The files a part's request names, as the diff writes them, and how many are left out. */
43
+ interface ListedFiles {
44
+ readonly files: readonly string[];
45
+ readonly unlisted: number;
46
+ }
47
+ /**
48
+ * Plan a profile's research of the filtered `diff`, whose sections are `sections`, before any stage runs.
49
+ * The research is one request holding the whole diff, which is what 0.5.0 sent, when:
50
+ * 1. the research provider states no room: no request is built to ask, so no nonce is drawn;
51
+ * 2. the room of the one-request research with an empty diff is no safe integer or is negative: its guard
52
+ * then refuses the request as it always did;
53
+ * 3. the diff's `tokenBound` is within the lesser of `partTokens` and that room;
54
+ * 4. the room of a part's request with an empty diff, its parts block at its widest (a position and a
55
+ * count of as many digits as the diff has lines, which no packing has more parts than), is no safe
56
+ * integer or is negative;
57
+ * 5. the packing sets a hunk aside while the one request still holds the whole diff: that hunk fits the
58
+ * one request but not a part's, which carries the parts block, and 0.5.0 read it, so nothing it read is
59
+ * left unread now.
60
+ * Otherwise it is the packing of the sections into parts of at most `partTokens` that fit that room (see
61
+ * `packParts`), with the change's files its requests name: at most 100, and at most a quarter of the
62
+ * lesser of `partTokens` and the one request's room, so the list stays small beside the diff of a part. When that
63
+ * packing sets a unit aside and the list names a file, the sections are packed again at the room of a parts
64
+ * block that lists no name (`and <n> more` alone), asked at the same widest position, because the list
65
+ * may be what left the unit out: the second packing and its block are kept when it sets fewer units aside,
66
+ * else the first, and the rule above (5) applies to the packing kept.
67
+ */
68
+ export declare function planResearch(run: ProfileRun, diff: string, sections: readonly DiffSection[], partTokens: number): ResearchPlan;
69
+ /**
70
+ * Turn one research reply into what the panel receives: `checkReplies` of that reply alone, unlabelled, so
71
+ * its gaps and its errors are the ones `checkReplies` states.
35
72
  *
36
73
  * @throws OutputError when the reply is not one JSON object holding a `findings` array and nothing else
37
74
  * @throws RangeError when `maxFindings` is not a positive integer
38
75
  */
39
- export declare function checkReply(text: string, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): ResearchOutcome;
76
+ export declare function checkReply(text: string, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): Omit<ResearchOutcome, 'parts'>;
40
77
  /**
41
- * The research stage of one profile: one call to its research provider, with the profile's
42
- * research instructions, the diff and the guidelines, whose reply `checkReply` turns into what the
43
- * panel receives. Each finding dropped for citing code outside the diff is reported by a
44
- * `finding:invalid` event, and each gap by an `incomplete` event. A research request its provider
45
- * refused as too large (a `too-large` `ProviderError`) was not sent: the profile reviews nothing,
46
- * records one `request-too-large` gap, and the other profiles run. Any other failed research
47
- * call, or a reply that is not a valid envelope, fails the profile and aborts the review where it
48
- * fails (`callProvider` aborts it for the call), so no other profile starts a call after it.
78
+ * Turn the research replies of a profile, in the parts' order, into what the panel receives. Each reply is
79
+ * parsed strictly (a malformed envelope, or one with a key other than `findings`, throws, so it never reads
80
+ * as "no findings"), only the first `maxFindings` findings the replies list in all are read and checked
81
+ * against the diff, the earlier replies' first (the work spent on a reply built to flood the run stays
82
+ * bounded, whatever the entries hold), and nothing the harness read is dropped silently: a finding that
83
+ * does not match the reply schema (what planted text that closes a string early leaves behind), findings
84
+ * beyond the cap, counted over all the replies in one gap, and replies whose findings were all unusable,
85
+ * are recorded as incomplete, which fails the run (ADR-0012). A finding that cites code outside the diff,
86
+ * the whole diff of every part, is only dropped with its reason: it was read, and it is wrong. `invalid`
87
+ * holds only the reasons of the findings the check against the diff dropped, so an unreadable finding is
88
+ * reported once, in `incomplete`, with its reply's `label` before the reason when it has one. Every
89
+ * finding it keeps is named by `findingId` and tagged with `profile`, and every incomplete entry it
90
+ * records is tagged with `profile` too.
49
91
  *
50
- * @throws ProviderError, or whatever a custom provider throws, when the research call fails for any other reason than a refusal as too large
51
- * @throws OutputError when the reply is not one JSON object holding a `findings` array and nothing else
92
+ * @throws OutputError when a reply is not one JSON object holding a `findings` array and nothing else
93
+ * @throws RangeError when `maxFindings` is not a positive integer
94
+ */
95
+ export declare function checkReplies(replies: ReadonlyArray<{
96
+ readonly text: string;
97
+ readonly label?: string;
98
+ }>, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): Omit<ResearchOutcome, 'parts'>;
99
+ /**
100
+ * The research stage of one profile, as `plan` lays it out: a change within one request is researched by one
101
+ * call to its research provider, with the profile's research instructions, the diff and the guidelines, and a
102
+ * large change is researched in parts, one call each, whose replies `checkReplies` turns into what the panel
103
+ * receives. Each finding dropped for citing code outside the diff is reported by a `finding:invalid` event,
104
+ * and each gap by an `incomplete` event.
105
+ *
106
+ * A change in one request (no packing, or a packing of one part, whose text is that part's) goes through
107
+ * one call. A research request its provider refused as too large (a `too-large` `ProviderError`) was not
108
+ * sent: the profile reviews nothing, records one `request-too-large` gap, and the other profiles run. For
109
+ * any other failed research, the call after its retries or a reply that is not a valid envelope, a gating
110
+ * profile fails and aborts the review where it fails (`onFailure` aborts it for the call), so no other
111
+ * profile starts a call after it; an advisory profile's failure is its own `research-failed` gap, in words
112
+ * the code writes, and the other profiles run. A research request a limit stopped (the token cap refused it
113
+ * or left no room for it, or the review's deadline ended it) is no failure of either kind: the outcome holds
114
+ * no finding and names the limit in `parts`, which the review turns into the profile's one gap for that
115
+ * limit, a gating profile's included. A packing of none, where no part holds any of the diff, makes no call, and
116
+ * neither does a part whose text is blank (white space only, as the text before a diff's first header can be,
117
+ * when every other unit was set aside): there is nothing to ask a model, so its outcome is `reviewed`.
118
+ *
119
+ * A packing of several parts runs `ctx.concurrency` workers of this profile, each taking the next part, in
120
+ * order, while one is left, and a call of each through the review's one limit, so the review's concurrency
121
+ * holds across profiles. Each part fails as a one-request research does, and a reply's envelope is checked
122
+ * as it arrives: a gating profile's failed call or unreadable envelope aborts the review where it fails, so
123
+ * no queued part starts and the review rejects with the first reason, and an advisory profile's is that
124
+ * part's `research-failed`, while its other parts go on. Once a part ends with a limit, the profile's parts
125
+ * not yet taken are stopped by the same limit without a call: each would be built and counted only to be
126
+ * refused, and the gap counts them, failing closed. Once every part has answered, the replies are read in
127
+ * the parts' order, up to `maxFindings` findings in all, each checked against the whole diff, and a finding
128
+ * two parts report is dropped by the dedup stage. The gaps come in this order, each counting parts: the
129
+ * requests refused as too large, then the parts that failed, then the reading's. The events follow: the
130
+ * `finding:invalid` ones, then the `incomplete` ones.
131
+ *
132
+ * A review that is aborted rejects with its reason, never with a gap.
133
+ *
134
+ * @throws ProviderError, or whatever a custom provider throws, when a gating profile's research call fails for any other reason than a refusal as too large
135
+ * @throws OutputError when a gating profile's reply is not one JSON object holding a `findings` array and nothing else
52
136
  */
53
- export declare function research(ctx: RunContext, run: ProfileRun, diff: string, sections: ReadonlyMap<string, string>): Promise<ResearchOutcome>;
137
+ export declare function research(ctx: RunContext, run: ProfileRun, plan: ResearchPlan, diff: string, sections: ReadonlyMap<string, string>): Promise<ResearchOutcome>;
138
+ export {};