@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
@@ -1,10 +1,25 @@
1
+ import type { Clock } from '../clock.ts';
1
2
  import type { Limiter } from '../concurrency.ts';
3
+ import type { ProviderErrorKind } from '../errors.ts';
4
+ import type { Ledger } from '../limits.ts';
2
5
  import type { CompletionRequest, EventSink, Provider } from '../ports.ts';
3
6
  import type { ProviderRef, StageName, Thresholds, Usage } from '../types.ts';
4
- /** A provider as a compiled profile holds it: the object it calls, and the ref captured at creation that events and meta report. */
7
+ /**
8
+ * A provider as a compiled profile holds it: the object it calls, the ref captured at creation that
9
+ * events and meta report, the deadline of each of its attempts, the retries of a call, and the worst case
10
+ * and the room it states.
11
+ */
5
12
  export interface Target {
6
13
  readonly provider: Provider;
7
14
  readonly ref: Readonly<ProviderRef>;
15
+ /** The deadline of one attempt, in milliseconds: what the provider stated when the quorum was created, else the default. */
16
+ readonly timeoutMs: number;
17
+ /** The retries of a call after its first attempt: what the provider stated when the quorum was created, else none. */
18
+ readonly retries: number;
19
+ /** The worst case of one attempt the provider stated when the quorum was created, when it is a function; `reservationOf` reads its result. */
20
+ readonly worstCase: ((request: CompletionRequest) => unknown) | undefined;
21
+ /** The room the provider stated when the quorum was created, when it is a function; `roomOf` reads its result. */
22
+ readonly room: ((request: CompletionRequest) => unknown) | undefined;
8
23
  }
9
24
  /** One lens of a compiled profile: its vote instructions, rendered once, and its own provider. */
10
25
  export interface LensRun extends Target {
@@ -33,24 +48,49 @@ export interface ProfileRun {
33
48
  export interface RunContext {
34
49
  /** The review's one concurrency limit, shared by every profile. */
35
50
  readonly limit: Limiter;
51
+ /**
52
+ * The review's one token ledger, shared by every profile: each attempt of a call reserves its worst case in
53
+ * it before the attempt is sent and settles after, inside the call's slot, so the attempts in flight can
54
+ * never pass the cap between them.
55
+ */
56
+ readonly ledger: Ledger;
36
57
  /** Delivers one event of the review to the sink, as a copy; it delivers nothing once the review is aborted. */
37
58
  readonly emit: EventSink;
38
59
  /**
39
- * Aborted when the caller's signal is, when the event sink throws, when a profile's research fails
40
- * or when the profiles' run rejects: every stage and every call checks it, and every request
41
- * carries it.
60
+ * Aborted when the caller's signal is, when the event sink throws, when a gating profile's research fails
61
+ * or when the profiles' run rejects: every stage and every call checks it, and every attempt
62
+ * carries a signal of its own, which `stop` and the attempt's own deadline abort.
42
63
  */
43
64
  readonly signal: AbortSignal;
65
+ /**
66
+ * The review's signal joined to its deadline's: aborted by whichever comes first, with that one's reason, which
67
+ * is the deadline's `LimitError` when it is the deadline. The slot's entry, the ledger's wait, every attempt and
68
+ * every backoff read it, so the deadline ends them all at once and no queued call starts. It is no abort of the
69
+ * review: `emit`, `stage` and the stages' catches keep reading `signal`, so an interrupt still rejects with its
70
+ * reason and the events still flow after the deadline, and what the deadline stopped is a gap.
71
+ */
72
+ readonly stop: AbortSignal;
73
+ /** When the review's deadline falls, `at` on the review's clock, and its length `ms`: the retry policy reads the time left from it. */
74
+ readonly deadline: {
75
+ readonly at: number;
76
+ readonly ms: number;
77
+ };
44
78
  /**
45
79
  * Aborts the review with `error`, unless it is already aborted, so a caller's abort reason or a
46
- * sink's error stays the reason. A research failure, the call or its reply, calls it where it
47
- * fails, so no other profile starts a call after it; a research request refused as too large is
48
- * a gap, not a failure, and does not.
80
+ * sink's error stays the reason. A gating profile's research failure, the call or its reply, calls
81
+ * it where it fails, so no other profile starts a call after it; an advisory profile's research
82
+ * failure is a gap, like a research request refused as too large, and does not.
49
83
  */
50
84
  readonly fail: (error: unknown) => void;
51
85
  /** How many findings of a research reply each profile sends to the panel. */
52
86
  readonly maxFindings: number;
87
+ /** The review's concurrency: how many parts of its research one profile has in flight at once. */
88
+ readonly concurrency: number;
89
+ /** The time and the randomness the call path reads: the system's, unless a spec injects its own. */
90
+ readonly clock: Clock;
53
91
  }
92
+ /** The value of an own data property of an object, else undefined: a getter is never run, an inherited property or a throwing proxy never matches. */
93
+ export declare function ownData(value: unknown, key: string): unknown;
54
94
  /**
55
95
  * True for a refusal as too large: an object whose own data property `kind` is `'too-large'`, which is what a
56
96
  * provider raises when a request may not fit its model's context, before sending it. It is matched by that
@@ -59,8 +99,24 @@ export interface RunContext {
59
99
  * never runs a getter and never throws.
60
100
  */
61
101
  export declare function isTooLarge(error: unknown): boolean;
102
+ /**
103
+ * What a failed call says of itself, as facts: the own data `kind` when it is one of `PROVIDER_ERROR_KINDS`,
104
+ * and for an `http` failure its own data `status` when that is an integer from 100 to 599. A message, which can
105
+ * quote a server, is never read. It is matched by those properties, not by class, as `isTooLarge` is, and it
106
+ * never runs a getter and never throws: any other value, a kind of no provider's included, is undefined.
107
+ */
108
+ export declare function providerFailure(error: unknown): {
109
+ readonly kind: ProviderErrorKind;
110
+ readonly status?: number;
111
+ } | undefined;
62
112
  /** What a refusal as too large says: its own data string `message`, else a fixed text, never anything else from the object. */
63
113
  export declare function refusalMessage(refusal: unknown): string;
114
+ /**
115
+ * The usage of one more attempt added to a running total: both sums are of the attempts that
116
+ * reported valid counts, and `costUsd` is summed over those that reported one. With no more usage
117
+ * the total stays as it is.
118
+ */
119
+ export declare function addUsage(total: Usage | undefined, more: Usage | undefined): Usage | undefined;
64
120
  /**
65
121
  * The usage a failed call's thrown value carries, when its counts can be trusted: its own data property
66
122
  * `usage`, and that object's own data `inputTokens`, `outputTokens` and `costUsd`, checked as a reply's
@@ -75,28 +131,80 @@ export interface Requester {
75
131
  readonly role: 'research' | 'vote';
76
132
  readonly lens?: string;
77
133
  }
134
+ /**
135
+ * A provider as a run holds it: the ref captured now, which events and meta report, and its
136
+ * deadline and retries, each read as own data and taken only when it passes its check, else the
137
+ * default: 600000 ms and no retry. The quorum's checks ran first, so a plain object's values are the
138
+ * ones they passed; a proxy that answers the check and this read differently still gets an in-range
139
+ * deadline and no retry, never an unbounded one. The worst case it states is its own data value when
140
+ * that is a function, else none, and so is the room it states: a getter is never run, and an inherited method
141
+ * states nothing.
142
+ */
143
+ export declare function targetOf(provider: Provider): Target;
144
+ /**
145
+ * The tokens one attempt of `request` is reserved: the worst case the provider states, called once with the
146
+ * request and the provider as `this`, when it returns a safe integer of at least 1. A provider that states
147
+ * none, a result that is anything else (a promise included, whose rejection is marked handled) and a throw
148
+ * all reserve the core's own count of the request plus
149
+ * `TEMPLATE_TOKENS` for what a server adds and `DEFAULT_REPLY_TOKENS` for the reply, so a worst case that
150
+ * misbehaves never reserves nothing. It never throws.
151
+ */
152
+ export declare function reservationOf(target: Target, request: CompletionRequest): number;
153
+ /**
154
+ * The room the provider states for `request`: how many more tokens of text it could hold and still fit the
155
+ * provider's window, called once with the request and the provider as `this`, when it returns a safe integer,
156
+ * 0 and a negative one included. A provider that states none, a result that is anything else (a promise
157
+ * included, whose rejection is marked handled) and a throw all state nothing, which is `undefined`, and the
158
+ * caller then reviews as it does for a provider that states no room. It never throws.
159
+ */
160
+ export declare function roomOf(target: Target, request: CompletionRequest): number | undefined;
78
161
  /** Whole milliseconds since `started`, a `performance.now()` reading. */
79
162
  export declare function elapsed(started: number): number;
80
163
  /**
81
164
  * Call a provider inside the review's concurrency limit and return its reply text. The review's
82
- * signal is checked inside the slot, before the request is built, so a call still queued when the
83
- * review is aborted never starts. `buildRequest` runs inside the slot once that check passes: a
84
- * request holds the diff or a section of it, and building it only there keeps the requests a
165
+ * stop is checked inside the slot, before the request is built, so a call still queued when the review
166
+ * is aborted or reaches its deadline never starts. `buildRequest` runs inside the slot once that check
167
+ * passes: a request holds the diff or a section of it, and building it only there keeps the requests a
85
168
  * review holds at once to its concurrency, whatever the number of findings and lenses (ADR-0009).
86
- * The request carries the signal, so the provider can stop a call in flight. A failed research
87
- * call aborts the review through `ctx.fail` before it leaves its slot, so the queued call the slot
88
- * goes to next never starts, unless the provider refused the request as too large: that refusal is
89
- * a gap, never a reason to stop the other profiles, so the research stage records it. A failed vote
90
- * does not abort the review, since the panel records it. The duration is measured inside the slot,
91
- * once the request is built: the provider's latency, not the time the call waited for a slot or
92
- * took to build its request. A reply whose text is not a string is a `ProviderError`. Each call
93
- * emits one `call` event, which names the provider by the ref captured at creation, never by the
94
- * live object: failed, before the error is rethrown, with the usage its error carries when its counts
95
- * are valid, or ok, with the usage when its counts are valid. The ok event is emitted outside the
96
- * `try` that catches the provider's failure, so a sink that throws on it is never reported as a
97
- * failed call.
169
+ * The call runs its attempts inside its slot, retried as `retryWait` decides, the waits between
170
+ * them holding the slot: the review's abort ends a wait at once, and no failure is retried once the
171
+ * review is aborted. Each attempt has the provider's deadline, and the provider is handed the
172
+ * attempt's own signal, so it can stop a call in flight: the review's abort settles the attempt at
173
+ * once, without waiting for the provider.
174
+ *
175
+ * The review's deadline ends the call's attempt and its waits for room and between attempts at once, as an
176
+ * abort does, but with its own failure, a `LimitError` that is no attempt's `timeout`; a call still queued for
177
+ * its slot ends there when its turn comes, before it builds its request; and no failure is retried once the
178
+ * deadline has passed. A failure the retry policy would have retried, which the stop alone prevents, ends the
179
+ * call with the stop's reason, the deadline's `LimitError` or the interrupt's, never with the failure, so a
180
+ * deadline is not recorded as a failure it cut short; a failure the policy would not have retried keeps its own
181
+ * error. The retry policy is told the time the review has left, so a server's hint longer than it ends the
182
+ * call with its last failure.
183
+ *
184
+ * Each attempt, the first and every retry, reserves the call's worst case (`reservationOf`, taken once
185
+ * the request is built) in the review's ledger before it is sent, and settles it once it ends, inside the
186
+ * slot: at the usage its reply or its failure reports, at nothing when the server refused it before any
187
+ * work, else at the whole reservation. An attempt that does not fit beside what was settled is never
188
+ * sent, and the call fails with the cap's `LimitError`; one that fits but not beside the attempts in
189
+ * flight waits for them, holding its slot, and the review's abort or deadline ends that wait too. A call a limit
190
+ * stops before its first attempt sends no `call` event, since no provider was called; one it stops
191
+ * after an attempt sends its failed event first, as any failed call does.
192
+ *
193
+ * A call that fails once its request is built, for any reason, ends through one place: it sends its
194
+ * failed `call` event when an attempt was made, then hands that failure and the attempts made, 0 when
195
+ * none, to `onFailure`, once, inside its slot, and rethrows. The research stage aborts the review there
196
+ * for a gating profile, so the queued call the slot goes to next never starts; a failed vote has no
197
+ * `onFailure`: the panel records it. The duration is measured inside the slot, from the first attempt,
198
+ * once the request is built, to the call's end, the waits included: the provider's latency, not the time
199
+ * the call waited for a slot or for room, or took to build its request. A reply whose text is not a string
200
+ * is a `ProviderError`. Each call emits one `call` event, which names the provider by the ref captured at
201
+ * creation, never by the live object, and counts its attempts when it made more than one: failed, before
202
+ * the error is rethrown, with the usage summed over its attempts when their counts are valid, or ok, with
203
+ * that usage; both carry `spent`, the sum of what its attempts settled at. The ok event is emitted outside
204
+ * the `try` that catches the provider's failure, so a sink that throws on it is never reported as a failed
205
+ * call.
98
206
  */
99
- export declare function callProvider(ctx: RunContext, requester: Requester, target: Target, buildRequest: () => CompletionRequest): Promise<string>;
207
+ export declare function callProvider(ctx: RunContext, requester: Requester, target: Target, buildRequest: () => CompletionRequest, onFailure?: (error: unknown, attempts: number) => void): Promise<string>;
100
208
  /**
101
209
  * Run one stage of a profile, sync or async, between its `stage:start` and `stage:end` events. The
102
210
  * review's signal is checked before the stage starts, not after its step: an abort during the step
@@ -1,9 +1,13 @@
1
- import { ProviderError } from "../errors.js";
1
+ import { PROVIDER_ERROR_KINDS, ProviderError } from "../errors.js";
2
+ import { settlementOf } from "../limits.js";
2
3
  import { isRecord } from "../output.js";
4
+ import { DEFAULT_TIMEOUT_MS, MAX_STATED_TIMEOUT_MS, retriesProblem, timeoutProblem } from "../ports.js";
5
+ import { isTimeout, retryWait } from "../retry.js";
6
+ import { DEFAULT_REPLY_TOKENS, requestTokens, TEMPLATE_TOKENS } from "../tokens.js";
3
7
  /** What a refusal as too large says when it holds no message of its own. */
4
8
  const REFUSAL_FALLBACK = 'refused as too large';
5
9
  /** The value of an own data property of an object, else undefined: a getter is never run, an inherited property or a throwing proxy never matches. */
6
- function ownData(value, key) {
10
+ export function ownData(value, key) {
7
11
  if (typeof value !== 'object' || value === null)
8
12
  return undefined;
9
13
  try {
@@ -26,6 +30,21 @@ function ownData(value, key) {
26
30
  export function isTooLarge(error) {
27
31
  return ownData(error, 'kind') === 'too-large';
28
32
  }
33
+ /**
34
+ * What a failed call says of itself, as facts: the own data `kind` when it is one of `PROVIDER_ERROR_KINDS`,
35
+ * and for an `http` failure its own data `status` when that is an integer from 100 to 599. A message, which can
36
+ * quote a server, is never read. It is matched by those properties, not by class, as `isTooLarge` is, and it
37
+ * never runs a getter and never throws: any other value, a kind of no provider's included, is undefined.
38
+ */
39
+ export function providerFailure(error) {
40
+ const kind = PROVIDER_ERROR_KINDS.find(known => known === ownData(error, 'kind'));
41
+ if (kind === undefined)
42
+ return undefined;
43
+ const status = ownData(error, 'status');
44
+ return kind === 'http' && typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599
45
+ ? { kind, status }
46
+ : { kind };
47
+ }
29
48
  /** What a refusal as too large says: its own data string `message`, else a fixed text, never anything else from the object. */
30
49
  export function refusalMessage(refusal) {
31
50
  const message = ownData(refusal, 'message');
@@ -33,6 +52,22 @@ export function refusalMessage(refusal) {
33
52
  ? message
34
53
  : REFUSAL_FALLBACK;
35
54
  }
55
+ /**
56
+ * The usage of one more attempt added to a running total: both sums are of the attempts that
57
+ * reported valid counts, and `costUsd` is summed over those that reported one. With no more usage
58
+ * the total stays as it is.
59
+ */
60
+ export function addUsage(total, more) {
61
+ if (more === undefined)
62
+ return total;
63
+ const sum = { inputTokens: (total?.inputTokens ?? 0) + more.inputTokens, outputTokens: (total?.outputTokens ?? 0) + more.outputTokens };
64
+ const costUsd = more.costUsd === undefined
65
+ ? total?.costUsd
66
+ : (total?.costUsd ?? 0) + more.costUsd;
67
+ if (costUsd !== undefined)
68
+ sum.costUsd = costUsd;
69
+ return sum;
70
+ }
36
71
  /**
37
72
  * The usage a failed call's thrown value carries, when its counts can be trusted: its own data property
38
73
  * `usage`, and that object's own data `inputTokens`, `outputTokens` and `costUsd`, checked as a reply's
@@ -48,71 +83,321 @@ export function failureUsage(error) {
48
83
  costUsd: ownData(usage, 'costUsd'),
49
84
  });
50
85
  }
86
+ /**
87
+ * A provider as a run holds it: the ref captured now, which events and meta report, and its
88
+ * deadline and retries, each read as own data and taken only when it passes its check, else the
89
+ * default: 600000 ms and no retry. The quorum's checks ran first, so a plain object's values are the
90
+ * ones they passed; a proxy that answers the check and this read differently still gets an in-range
91
+ * deadline and no retry, never an unbounded one. The worst case it states is its own data value when
92
+ * that is a function, else none, and so is the room it states: a getter is never run, and an inherited method
93
+ * states nothing.
94
+ */
95
+ export function targetOf(provider) {
96
+ const timeoutMs = ownData(provider, 'timeoutMs');
97
+ const retries = ownData(provider, 'retries');
98
+ const worstCase = ownData(provider, 'worstCase');
99
+ const room = ownData(provider, 'room');
100
+ return {
101
+ provider,
102
+ ref: Object.freeze({ id: provider.id, model: provider.model }),
103
+ timeoutMs: timeoutProblem(timeoutMs, MAX_STATED_TIMEOUT_MS) === undefined
104
+ ? timeoutMs
105
+ : DEFAULT_TIMEOUT_MS,
106
+ retries: retriesProblem(retries) === undefined
107
+ ? retries
108
+ : 0,
109
+ worstCase: typeof worstCase === 'function'
110
+ ? worstCase
111
+ : undefined,
112
+ room: typeof room === 'function'
113
+ ? room
114
+ : undefined,
115
+ };
116
+ }
117
+ /**
118
+ * The safe integer a provider's stated function returns for `request`, called once, synchronously, with the
119
+ * request and the provider as `this`: undefined for anything else. A result that is not a safe integer (a
120
+ * promise included, whose rejection is marked handled) and a throw state nothing. It never throws.
121
+ */
122
+ function statedInteger(stating, provider, request) {
123
+ try {
124
+ const stated = Reflect.apply(stating, provider, [request]);
125
+ if (typeof stated === 'number' && Number.isSafeInteger(stated))
126
+ return stated;
127
+ // It is called synchronously: a promise states nothing, and a rejected one must not crash the process.
128
+ if ((typeof stated === 'object' && stated !== null) || typeof stated === 'function') {
129
+ Promise.resolve(stated).then(undefined, () => { });
130
+ }
131
+ }
132
+ catch {
133
+ // A function that throws states nothing.
134
+ }
135
+ return undefined;
136
+ }
137
+ /**
138
+ * The tokens one attempt of `request` is reserved: the worst case the provider states, called once with the
139
+ * request and the provider as `this`, when it returns a safe integer of at least 1. A provider that states
140
+ * none, a result that is anything else (a promise included, whose rejection is marked handled) and a throw
141
+ * all reserve the core's own count of the request plus
142
+ * `TEMPLATE_TOKENS` for what a server adds and `DEFAULT_REPLY_TOKENS` for the reply, so a worst case that
143
+ * misbehaves never reserves nothing. It never throws.
144
+ */
145
+ export function reservationOf(target, request) {
146
+ const stated = target.worstCase === undefined
147
+ ? undefined
148
+ : statedInteger(target.worstCase, target.provider, request);
149
+ return stated !== undefined && stated >= 1
150
+ ? stated
151
+ : requestTokens(request) + TEMPLATE_TOKENS + DEFAULT_REPLY_TOKENS;
152
+ }
153
+ /**
154
+ * The room the provider states for `request`: how many more tokens of text it could hold and still fit the
155
+ * provider's window, called once with the request and the provider as `this`, when it returns a safe integer,
156
+ * 0 and a negative one included. A provider that states none, a result that is anything else (a promise
157
+ * included, whose rejection is marked handled) and a throw all state nothing, which is `undefined`, and the
158
+ * caller then reviews as it does for a provider that states no room. It never throws.
159
+ */
160
+ export function roomOf(target, request) {
161
+ return target.room === undefined
162
+ ? undefined
163
+ : statedInteger(target.room, target.provider, request);
164
+ }
51
165
  /** Whole milliseconds since `started`, a `performance.now()` reading. */
52
166
  export function elapsed(started) {
53
167
  return Math.round(performance.now() - started);
54
168
  }
55
169
  /**
56
170
  * Call a provider inside the review's concurrency limit and return its reply text. The review's
57
- * signal is checked inside the slot, before the request is built, so a call still queued when the
58
- * review is aborted never starts. `buildRequest` runs inside the slot once that check passes: a
59
- * request holds the diff or a section of it, and building it only there keeps the requests a
171
+ * stop is checked inside the slot, before the request is built, so a call still queued when the review
172
+ * is aborted or reaches its deadline never starts. `buildRequest` runs inside the slot once that check
173
+ * passes: a request holds the diff or a section of it, and building it only there keeps the requests a
60
174
  * review holds at once to its concurrency, whatever the number of findings and lenses (ADR-0009).
61
- * The request carries the signal, so the provider can stop a call in flight. A failed research
62
- * call aborts the review through `ctx.fail` before it leaves its slot, so the queued call the slot
63
- * goes to next never starts, unless the provider refused the request as too large: that refusal is
64
- * a gap, never a reason to stop the other profiles, so the research stage records it. A failed vote
65
- * does not abort the review, since the panel records it. The duration is measured inside the slot,
66
- * once the request is built: the provider's latency, not the time the call waited for a slot or
67
- * took to build its request. A reply whose text is not a string is a `ProviderError`. Each call
68
- * emits one `call` event, which names the provider by the ref captured at creation, never by the
69
- * live object: failed, before the error is rethrown, with the usage its error carries when its counts
70
- * are valid, or ok, with the usage when its counts are valid. The ok event is emitted outside the
71
- * `try` that catches the provider's failure, so a sink that throws on it is never reported as a
72
- * failed call.
175
+ * The call runs its attempts inside its slot, retried as `retryWait` decides, the waits between
176
+ * them holding the slot: the review's abort ends a wait at once, and no failure is retried once the
177
+ * review is aborted. Each attempt has the provider's deadline, and the provider is handed the
178
+ * attempt's own signal, so it can stop a call in flight: the review's abort settles the attempt at
179
+ * once, without waiting for the provider.
180
+ *
181
+ * The review's deadline ends the call's attempt and its waits for room and between attempts at once, as an
182
+ * abort does, but with its own failure, a `LimitError` that is no attempt's `timeout`; a call still queued for
183
+ * its slot ends there when its turn comes, before it builds its request; and no failure is retried once the
184
+ * deadline has passed. A failure the retry policy would have retried, which the stop alone prevents, ends the
185
+ * call with the stop's reason, the deadline's `LimitError` or the interrupt's, never with the failure, so a
186
+ * deadline is not recorded as a failure it cut short; a failure the policy would not have retried keeps its own
187
+ * error. The retry policy is told the time the review has left, so a server's hint longer than it ends the
188
+ * call with its last failure.
189
+ *
190
+ * Each attempt, the first and every retry, reserves the call's worst case (`reservationOf`, taken once
191
+ * the request is built) in the review's ledger before it is sent, and settles it once it ends, inside the
192
+ * slot: at the usage its reply or its failure reports, at nothing when the server refused it before any
193
+ * work, else at the whole reservation. An attempt that does not fit beside what was settled is never
194
+ * sent, and the call fails with the cap's `LimitError`; one that fits but not beside the attempts in
195
+ * flight waits for them, holding its slot, and the review's abort or deadline ends that wait too. A call a limit
196
+ * stops before its first attempt sends no `call` event, since no provider was called; one it stops
197
+ * after an attempt sends its failed event first, as any failed call does.
198
+ *
199
+ * A call that fails once its request is built, for any reason, ends through one place: it sends its
200
+ * failed `call` event when an attempt was made, then hands that failure and the attempts made, 0 when
201
+ * none, to `onFailure`, once, inside its slot, and rethrows. The research stage aborts the review there
202
+ * for a gating profile, so the queued call the slot goes to next never starts; a failed vote has no
203
+ * `onFailure`: the panel records it. The duration is measured inside the slot, from the first attempt,
204
+ * once the request is built, to the call's end, the waits included: the provider's latency, not the time
205
+ * the call waited for a slot or for room, or took to build its request. A reply whose text is not a string
206
+ * is a `ProviderError`. Each call emits one `call` event, which names the provider by the ref captured at
207
+ * creation, never by the live object, and counts its attempts when it made more than one: failed, before
208
+ * the error is rethrown, with the usage summed over its attempts when their counts are valid, or ok, with
209
+ * that usage; both carry `spent`, the sum of what its attempts settled at. The ok event is emitted outside
210
+ * the `try` that catches the provider's failure, so a sink that throws on it is never reported as a failed
211
+ * call.
73
212
  */
74
- export async function callProvider(ctx, requester, target, buildRequest) {
213
+ export async function callProvider(ctx, requester, target, buildRequest, onFailure) {
75
214
  return ctx.limit(async () => {
76
- ctx.signal.throwIfAborted();
215
+ ctx.stop.throwIfAborted();
77
216
  const request = buildRequest();
78
- const started = performance.now();
217
+ const reservation = reservationOf(target, request);
218
+ const started = ctx.clock.now();
219
+ const took = () => Math.round(ctx.clock.now() - started);
220
+ let attempts = 0;
221
+ let usage;
222
+ let spent = 0;
223
+ let timedOut = false;
79
224
  let response;
80
- try {
81
- response = await target.provider.complete({ ...request, signal: ctx.signal });
82
- if (typeof response?.text !== 'string')
83
- throw new ProviderError({ providerId: target.ref.id, kind: 'invalid-response', message: 'returned no reply text' });
84
- }
85
- catch (error) {
86
- const failedUsage = failureUsage(error);
87
- ctx.emit({
88
- type: 'call',
89
- ...requester,
90
- provider: target.ref,
91
- durationMs: elapsed(started),
92
- ok: false,
93
- ...(failedUsage === undefined
94
- ? {}
95
- : { usage: failedUsage }),
96
- });
97
- // Still inside the slot: the queued call it is handed to next sees the abort and never starts.
98
- if (requester.role === 'research' && !isTooLarge(error))
99
- ctx.fail(error);
100
- throw error;
225
+ let replied;
226
+ /** Settles the attempt's reservation at `tokens`, which the call's `spent` adds. */
227
+ const settle = (tokens) => {
228
+ ctx.ledger.settle(reservation, tokens);
229
+ spent += tokens;
230
+ };
231
+ /** Ends the call with `error`: its failed event when an attempt was made, then `onFailure`; the error to throw. */
232
+ const end = (error) => {
233
+ if (attempts > 0) {
234
+ ctx.emit({
235
+ type: 'call',
236
+ ...requester,
237
+ provider: target.ref,
238
+ durationMs: took(),
239
+ ok: false,
240
+ ...counted(attempts, usage, spent),
241
+ });
242
+ }
243
+ // Still inside the slot: a review aborted here never starts the queued call the slot goes to next.
244
+ onFailure?.(error, attempts);
245
+ return error;
246
+ };
247
+ while (response === undefined) {
248
+ try {
249
+ await ctx.ledger.reserve(reservation, ctx.stop);
250
+ }
251
+ catch (error) {
252
+ throw end(error);
253
+ }
254
+ attempts += 1;
255
+ try {
256
+ const reply = await attempt(ctx, target, request);
257
+ if (typeof reply?.text !== 'string')
258
+ throw new ProviderError({ providerId: target.ref.id, kind: 'invalid-response', message: 'returned no reply text' });
259
+ // The reply's usage is read once, so its settlement and its event cannot disagree.
260
+ replied = checkedUsage(reply.usage);
261
+ settle(settlementOf(reservation, replied));
262
+ response = reply;
263
+ }
264
+ catch (error) {
265
+ const reported = failureUsage(error);
266
+ usage = addUsage(usage, reported);
267
+ const facts = failureFacts(error);
268
+ settle(settlementOf(reservation, reported, facts));
269
+ // A stopped review is asked as if it had time to spare, so a retry only the stop prevents is the stop's doing.
270
+ const wait = retryWait(facts, {
271
+ retried: attempts - 1,
272
+ retries: target.retries,
273
+ timedOut,
274
+ timeLeftMs: ctx.stop.aborted
275
+ ? Number.POSITIVE_INFINITY
276
+ : ctx.deadline.at - ctx.clock.now(),
277
+ }, ctx.clock.random);
278
+ if (wait === undefined)
279
+ throw end(error);
280
+ if (ctx.stop.aborted)
281
+ throw end(ctx.stop.reason);
282
+ timedOut ||= isTimeout(facts);
283
+ try {
284
+ await pause(ctx, wait);
285
+ }
286
+ catch (stopped) {
287
+ throw end(stopped);
288
+ }
289
+ }
101
290
  }
102
- const usage = checkedUsage(response.usage);
103
291
  ctx.emit({
104
292
  type: 'call',
105
293
  ...requester,
106
294
  provider: target.ref,
107
- durationMs: elapsed(started),
295
+ durationMs: took(),
108
296
  ok: true,
109
- ...(usage === undefined
110
- ? {}
111
- : { usage }),
297
+ ...counted(attempts, addUsage(usage, replied), spent),
112
298
  });
113
299
  return response.text;
114
300
  });
115
301
  }
302
+ /** The fields of a `call` event that hold what the call's attempts add up to: their number when above one, their summed usage when valid, and the tokens the cap counted. */
303
+ function counted(attempts, usage, spent) {
304
+ return {
305
+ ...(attempts > 1
306
+ ? { attempts }
307
+ : {}),
308
+ ...(usage === undefined
309
+ ? {}
310
+ : { usage }),
311
+ spent,
312
+ };
313
+ }
314
+ /** What the retry policy reads of a thrown value: its `kind`, `status`, `retryable` and `retryAfterMs` as own data, so a getter decides nothing and never runs. */
315
+ function failureFacts(error) {
316
+ return {
317
+ kind: ownData(error, 'kind'),
318
+ status: ownData(error, 'status'),
319
+ retryable: ownData(error, 'retryable'),
320
+ retryAfterMs: ownData(error, 'retryAfterMs'),
321
+ };
322
+ }
323
+ /**
324
+ * Wait `ms` milliseconds between two attempts of a call, which holds its slot meanwhile. The review's
325
+ * abort or deadline ends the wait at once: it rejects with the stop's reason, and the timer is cancelled.
326
+ * Each of the timer and the stop listener removes the other when it goes first.
327
+ */
328
+ function pause(ctx, ms) {
329
+ if (ctx.stop.aborted)
330
+ return Promise.reject(ctx.stop.reason);
331
+ return new Promise((resolve, reject) => {
332
+ let cancel = () => { };
333
+ function onAbort() {
334
+ cancel();
335
+ reject(ctx.stop.reason);
336
+ }
337
+ cancel = ctx.clock.timer(ms, () => {
338
+ ctx.stop.removeEventListener('abort', onAbort);
339
+ resolve();
340
+ });
341
+ ctx.stop.addEventListener('abort', onAbort, { once: true });
342
+ });
343
+ }
344
+ /**
345
+ * One attempt of a call, settled once, by the first of: the provider's reply or failure; its own
346
+ * deadline, as a `timeout` error of the core's own with the attempt's signal aborted with it as the
347
+ * reason; the review's stop, its abort or its deadline, with the stop's reason. The attempt's timer
348
+ * and the join to the review's stop go when it settles, on every path. A provider that throws before
349
+ * it returns a promise, or returns a plain object, is handled; whatever it does once the attempt
350
+ * settled is caught and ignored, and it is never an unhandled rejection. The join is one listener,
351
+ * not `AbortSignal.any`, so nothing builds up on a signal that outlives thousands of attempts.
352
+ */
353
+ function attempt(ctx, target, request) {
354
+ if (ctx.stop.aborted)
355
+ return Promise.reject(ctx.stop.reason);
356
+ const controller = new AbortController();
357
+ return new Promise((resolve, reject) => {
358
+ let settled = false;
359
+ let cancel = () => { };
360
+ /** True the first time, when it clears the timer and the listener; false once the attempt has settled. */
361
+ function done() {
362
+ if (settled)
363
+ return false;
364
+ settled = true;
365
+ cancel();
366
+ ctx.stop.removeEventListener('abort', onAbort);
367
+ return true;
368
+ }
369
+ function onAbort() {
370
+ if (!done())
371
+ return;
372
+ controller.abort(ctx.stop.reason);
373
+ reject(ctx.stop.reason);
374
+ }
375
+ cancel = ctx.clock.timer(target.timeoutMs, () => {
376
+ if (!done())
377
+ return;
378
+ const error = new ProviderError({ providerId: target.ref.id, kind: 'timeout', message: `no reply within ${target.timeoutMs} ms` });
379
+ controller.abort(error);
380
+ reject(error);
381
+ });
382
+ ctx.stop.addEventListener('abort', onAbort, { once: true });
383
+ let call;
384
+ try {
385
+ call = Promise.resolve(target.provider.complete({ ...request, signal: controller.signal }));
386
+ }
387
+ catch (error) {
388
+ if (done())
389
+ reject(error);
390
+ return;
391
+ }
392
+ call.then((response) => {
393
+ if (done())
394
+ resolve(response);
395
+ }, (error) => {
396
+ if (done())
397
+ reject(error);
398
+ });
399
+ });
400
+ }
116
401
  /**
117
402
  * Run one stage of a profile, sync or async, between its `stage:start` and `stage:end` events. The
118
403
  * review's signal is checked before the stage starts, not after its step: an abort during the step