@tobi-or-not/quorum 0.4.0 → 0.5.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 (71) hide show
  1. package/README.md +1 -1
  2. package/dist/bench/fingerprint.d.ts +7 -5
  3. package/dist/bench/fingerprint.js +22 -9
  4. package/dist/bench/records.d.ts +70 -0
  5. package/dist/bench/records.js +30 -0
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +29 -3
  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/main.d.ts +34 -14
  12. package/dist/cli/main.js +99 -20
  13. package/dist/cli/print-config.d.ts +8 -6
  14. package/dist/cli/print-config.js +21 -8
  15. package/dist/cli/render.d.ts +2 -2
  16. package/dist/cli/render.js +21 -2
  17. package/dist/config/env.d.ts +32 -19
  18. package/dist/config/env.js +95 -32
  19. package/dist/config/from-config.js +15 -3
  20. package/dist/config/resolve.d.ts +9 -1
  21. package/dist/config/resolve.js +17 -1
  22. package/dist/config/schema.d.ts +141 -5
  23. package/dist/config/schema.js +125 -12
  24. package/dist/core/clock.d.ts +17 -0
  25. package/dist/core/clock.js +14 -0
  26. package/dist/core/coverage.d.ts +49 -0
  27. package/dist/core/coverage.js +144 -0
  28. package/dist/core/diff.d.ts +24 -0
  29. package/dist/core/diff.js +63 -18
  30. package/dist/core/errors.d.ts +12 -3
  31. package/dist/core/errors.js +21 -2
  32. package/dist/core/exclude.d.ts +42 -0
  33. package/dist/core/exclude.js +189 -0
  34. package/dist/core/limits.d.ts +82 -0
  35. package/dist/core/limits.js +163 -0
  36. package/dist/core/output.d.ts +3 -2
  37. package/dist/core/output.js +3 -2
  38. package/dist/core/ports.d.ts +57 -2
  39. package/dist/core/ports.js +36 -1
  40. package/dist/core/quorum.d.ts +24 -8
  41. package/dist/core/quorum.js +187 -56
  42. package/dist/core/retry.d.ts +36 -0
  43. package/dist/core/retry.js +46 -0
  44. package/dist/core/stages/context.d.ts +118 -23
  45. package/dist/core/stages/context.js +304 -46
  46. package/dist/core/stages/panel.d.ts +5 -4
  47. package/dist/core/stages/panel.js +30 -11
  48. package/dist/core/stages/research.d.ts +15 -6
  49. package/dist/core/stages/research.js +75 -18
  50. package/dist/core/tokens.d.ts +31 -0
  51. package/dist/core/tokens.js +81 -0
  52. package/dist/core/types.d.ts +77 -10
  53. package/dist/index.d.ts +1 -1
  54. package/dist/providers/anthropic.d.ts +2 -1
  55. package/dist/providers/anthropic.js +8 -3
  56. package/dist/providers/claude-code.d.ts +51 -11
  57. package/dist/providers/claude-code.js +60 -25
  58. package/dist/providers/gemini.d.ts +4 -1
  59. package/dist/providers/gemini.js +63 -11
  60. package/dist/providers/http.d.ts +49 -4
  61. package/dist/providers/http.js +155 -14
  62. package/dist/providers/ollama.d.ts +3 -1
  63. package/dist/providers/ollama.js +11 -5
  64. package/dist/providers/openai-compatible.d.ts +3 -1
  65. package/dist/providers/openai-compatible.js +11 -5
  66. package/dist/providers/options.d.ts +12 -3
  67. package/dist/providers/options.js +30 -10
  68. package/dist/providers/size.d.ts +10 -14
  69. package/dist/providers/size.js +15 -69
  70. package/package.json +1 -1
  71. package/schema/quorum.schema.json +34 -1
@@ -0,0 +1,82 @@
1
+ /**
2
+ * The limits of a review: the token cap's plain rules and its ledger, the review's deadline, and the failure
3
+ * a limit ends a call with. A limit stops part of a review without failing it: the call path reserves each
4
+ * attempt's worst case here before it sends the attempt, the deadline ends every wait and attempt at once, and
5
+ * the gap a limit leaves is written from the votes and the research it stopped.
6
+ */
7
+ import { QuorumError } from './errors.ts';
8
+ import type { IncompleteEntry, Usage, Verdict } from './types.ts';
9
+ /** The most tokens, input and output, one review spends when `maxReviewTokens` is not set. */
10
+ export declare const DEFAULT_MAX_REVIEW_TOKENS = 2000000;
11
+ /** How long one review runs when `reviewTimeoutMs` is not set: 30 minutes. */
12
+ export declare const DEFAULT_REVIEW_TIMEOUT_MS = 1800000;
13
+ /** The problem with a `maxReviewTokens`, in words that say what to write, or undefined for a safe integer of at least 1. */
14
+ export declare function maxReviewTokensProblem(value: unknown): string | undefined;
15
+ /** The limits a review keeps to, in the order their gaps are listed. */
16
+ export type LimitName = 'token-cap' | 'review-deadline';
17
+ /**
18
+ * What a call ends with when a limit stops it. It is recognised by `instanceof` only, and a provider
19
+ * cannot raise one: an instance from a second copy of quorum is an unknown failure, which fails closed.
20
+ * It has no `kind`, so the retry policy never retries it and it is no provider's failure.
21
+ */
22
+ export declare class LimitError extends QuorumError {
23
+ readonly limit: LimitName;
24
+ constructor(limit: LimitName, message: string);
25
+ }
26
+ /** True for the failure a limit ends a call with. */
27
+ export declare function isLimit(error: unknown): error is LimitError;
28
+ /** What the ledger holds: the cap, the tokens settled so far and the tokens reserved by the attempts in flight. */
29
+ export interface Totals {
30
+ readonly cap: number;
31
+ readonly settled: number;
32
+ readonly reserved: number;
33
+ }
34
+ /** Whether an attempt goes at once, waits for the attempts in flight to settle, or can never fit. */
35
+ export type Fit = 'fits' | 'waits' | 'refused';
36
+ /**
37
+ * Where an attempt of `tokens` stands: refused when it does not fit beside what was settled, which only grows;
38
+ * waiting when it fits beside that but not beside the attempts in flight, which settle at what they spent or
39
+ * at their whole reservation; else fitting.
40
+ */
41
+ export declare function fitOf(totals: Totals, tokens: number): Fit;
42
+ /** What a failed attempt says of itself, as the call path read it: each as found, so either may be anything. */
43
+ export interface SettledFailure {
44
+ readonly kind: unknown;
45
+ readonly status: unknown;
46
+ }
47
+ /**
48
+ * The tokens an attempt counts once it ends. A valid usage comes first, even above the reservation. Without
49
+ * one, a failure that is a refusal as too large, or an `http` failure of a client status but 408, counts for
50
+ * nothing: no work was done. Anything else counts the whole reservation, so a failure that says nothing
51
+ * never costs less than it may have.
52
+ */
53
+ export declare function settlementOf(reserved: number, usage: Usage | undefined, failure?: SettledFailure): number;
54
+ /**
55
+ * One review's token ledger. `reserve` takes an attempt's worst case before it is sent: it resolves once the
56
+ * attempt fits beside what was settled and what the attempts in flight reserved, and rejects with the cap's
57
+ * `LimitError` when it can never fit, or with `stop`'s reason when `stop` aborts first. `settle` returns a
58
+ * reservation and adds what the attempt spent.
59
+ */
60
+ export interface Ledger {
61
+ readonly cap: number;
62
+ readonly reserve: (tokens: number, stop: AbortSignal) => Promise<void>;
63
+ readonly settle: (reserved: number, spent: number) => void;
64
+ }
65
+ /**
66
+ * A ledger for a cap of `cap` tokens. An attempt that waits queues, and each settlement admits the waiters in
67
+ * the order they began to wait, up to the first that still waits; one that can never fit leaves the queue. A
68
+ * newcomer that would fit while an earlier attempt waits waits behind it, so a stream of small votes never holds
69
+ * a large research request back. Nothing deadlocks: every reservation in flight settles, at worst at its
70
+ * attempt's deadline, and with none in flight the head of the queue either fits or is refused.
71
+ */
72
+ export declare function createLedger(cap: number): Ledger;
73
+ /**
74
+ * The gaps the limits leave in a profile, one entry per limit that stopped work, the token cap's first, or none:
75
+ * `research` names the limit that stopped its research request, and every vote of `verdicts` whose failure is a
76
+ * limit counts for it. Each detail names the limit with its setting, then what it stopped: `its research`,
77
+ * `<n> vote(s)`, or `its research and <n> vote(s)`.
78
+ */
79
+ export declare function limitGaps(profile: string, research: LimitName | undefined, verdicts: readonly Verdict[], limits: {
80
+ readonly cap: number;
81
+ readonly deadlineMs: number;
82
+ }): IncompleteEntry[];
@@ -0,0 +1,163 @@
1
+ /**
2
+ * The limits of a review: the token cap's plain rules and its ledger, the review's deadline, and the failure
3
+ * a limit ends a call with. A limit stops part of a review without failing it: the call path reserves each
4
+ * attempt's worst case here before it sends the attempt, the deadline ends every wait and attempt at once, and
5
+ * the gap a limit leaves is written from the votes and the research it stopped.
6
+ */
7
+ import { QuorumError } from "./errors.js";
8
+ /** The most tokens, input and output, one review spends when `maxReviewTokens` is not set. */
9
+ export const DEFAULT_MAX_REVIEW_TOKENS = 2_000_000;
10
+ /** How long one review runs when `reviewTimeoutMs` is not set: 30 minutes. */
11
+ export const DEFAULT_REVIEW_TIMEOUT_MS = 1_800_000;
12
+ /** What `maxReviewTokens` is when it is out of range: a whole number of tokens up to the largest the ledger adds exactly. */
13
+ const CAP_PROBLEM = `must be a whole number of tokens from 1 to ${Number.MAX_SAFE_INTEGER}`;
14
+ /** The problem with a `maxReviewTokens`, in words that say what to write, or undefined for a safe integer of at least 1. */
15
+ export function maxReviewTokensProblem(value) {
16
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1
17
+ ? undefined
18
+ : CAP_PROBLEM;
19
+ }
20
+ /** Every limit, in the order `limitGaps` lists their gaps. */
21
+ const LIMITS = ['token-cap', 'review-deadline'];
22
+ /**
23
+ * What a call ends with when a limit stops it. It is recognised by `instanceof` only, and a provider
24
+ * cannot raise one: an instance from a second copy of quorum is an unknown failure, which fails closed.
25
+ * It has no `kind`, so the retry policy never retries it and it is no provider's failure.
26
+ */
27
+ export class LimitError extends QuorumError {
28
+ limit;
29
+ constructor(limit, message) {
30
+ super(message);
31
+ this.limit = limit;
32
+ }
33
+ }
34
+ /** True for the failure a limit ends a call with. */
35
+ export function isLimit(error) {
36
+ return error instanceof LimitError;
37
+ }
38
+ /**
39
+ * Where an attempt of `tokens` stands: refused when it does not fit beside what was settled, which only grows;
40
+ * waiting when it fits beside that but not beside the attempts in flight, which settle at what they spent or
41
+ * at their whole reservation; else fitting.
42
+ */
43
+ export function fitOf(totals, tokens) {
44
+ if (totals.settled + tokens > totals.cap)
45
+ return 'refused';
46
+ return totals.settled + totals.reserved + tokens > totals.cap
47
+ ? 'waits'
48
+ : 'fits';
49
+ }
50
+ /** True for an integer status of 400 to 499 but 408: a server that refused the request before any work. */
51
+ function refusedBeforeWork(status) {
52
+ return typeof status === 'number' && Number.isInteger(status) && status >= 400 && status <= 499 && status !== 408;
53
+ }
54
+ /**
55
+ * The tokens an attempt counts once it ends. A valid usage comes first, even above the reservation. Without
56
+ * one, a failure that is a refusal as too large, or an `http` failure of a client status but 408, counts for
57
+ * nothing: no work was done. Anything else counts the whole reservation, so a failure that says nothing
58
+ * never costs less than it may have.
59
+ */
60
+ export function settlementOf(reserved, usage, failure) {
61
+ if (usage !== undefined)
62
+ return usage.inputTokens + usage.outputTokens;
63
+ if (failure !== undefined && (failure.kind === 'too-large' || (failure.kind === 'http' && refusedBeforeWork(failure.status))))
64
+ return 0;
65
+ return reserved;
66
+ }
67
+ /**
68
+ * A ledger for a cap of `cap` tokens. An attempt that waits queues, and each settlement admits the waiters in
69
+ * the order they began to wait, up to the first that still waits; one that can never fit leaves the queue. A
70
+ * newcomer that would fit while an earlier attempt waits waits behind it, so a stream of small votes never holds
71
+ * a large research request back. Nothing deadlocks: every reservation in flight settles, at worst at its
72
+ * attempt's deadline, and with none in flight the head of the queue either fits or is refused.
73
+ */
74
+ export function createLedger(cap) {
75
+ let settled = 0;
76
+ let reserved = 0;
77
+ const waiters = [];
78
+ const refusal = () => new LimitError('token-cap', `the review's token cap of ${cap} tokens leaves no room for this call`);
79
+ function wake() {
80
+ while (waiters.length > 0) {
81
+ const head = waiters[0];
82
+ const fit = fitOf({ cap, settled, reserved }, head.tokens);
83
+ if (fit === 'waits')
84
+ return;
85
+ waiters.shift();
86
+ if (fit === 'fits') {
87
+ reserved += head.tokens;
88
+ head.admit();
89
+ }
90
+ else {
91
+ head.refuse();
92
+ }
93
+ }
94
+ }
95
+ function reserve(tokens, stop) {
96
+ if (stop.aborted)
97
+ return Promise.reject(stop.reason);
98
+ const fit = fitOf({ cap, settled, reserved }, tokens);
99
+ if (fit === 'refused')
100
+ return Promise.reject(refusal());
101
+ if (fit === 'fits' && waiters.length === 0) {
102
+ reserved += tokens;
103
+ return Promise.resolve();
104
+ }
105
+ return new Promise((resolve, reject) => {
106
+ const waiter = {
107
+ tokens,
108
+ admit: () => {
109
+ stop.removeEventListener('abort', onAbort);
110
+ resolve();
111
+ },
112
+ refuse: () => {
113
+ stop.removeEventListener('abort', onAbort);
114
+ reject(refusal());
115
+ },
116
+ };
117
+ function onAbort() {
118
+ const index = waiters.indexOf(waiter);
119
+ if (index !== -1)
120
+ waiters.splice(index, 1);
121
+ reject(stop.reason);
122
+ wake();
123
+ }
124
+ waiters.push(waiter);
125
+ stop.addEventListener('abort', onAbort, { once: true });
126
+ });
127
+ }
128
+ function settle(was, spent) {
129
+ reserved -= was;
130
+ settled += spent;
131
+ wake();
132
+ }
133
+ return { cap, reserve, settle };
134
+ }
135
+ /**
136
+ * The gaps the limits leave in a profile, one entry per limit that stopped work, the token cap's first, or none:
137
+ * `research` names the limit that stopped its research request, and every vote of `verdicts` whose failure is a
138
+ * limit counts for it. Each detail names the limit with its setting, then what it stopped: `its research`,
139
+ * `<n> vote(s)`, or `its research and <n> vote(s)`.
140
+ */
141
+ export function limitGaps(profile, research, verdicts, limits) {
142
+ const failures = verdicts.flatMap(verdict => verdict.votes).map(lensVote => lensVote.failure?.kind);
143
+ const which = {
144
+ 'token-cap': `the review's token cap of ${limits.cap} tokens`,
145
+ 'review-deadline': `the review's deadline of ${limits.deadlineMs} ms`,
146
+ };
147
+ return LIMITS.flatMap((limit) => {
148
+ const votes = failures.filter(kind => kind === limit).length;
149
+ const stopped = [
150
+ ...research === limit
151
+ ? ['its research']
152
+ : [],
153
+ ...votes > 0
154
+ ? [`${votes} vote(s)`]
155
+ : [],
156
+ ];
157
+ return stopped.length === 0
158
+ ? []
159
+ : [
160
+ { profile, reason: limit, detail: `${which[limit]} stopped ${stopped.join(' and ')}` },
161
+ ];
162
+ });
163
+ }
@@ -36,8 +36,9 @@ export interface ResearchReply {
36
36
  }
37
37
  /**
38
38
  * Validate a research reply. The envelope must be exactly `{ findings: [...] }`: a missing or
39
- * non-array `findings` fails the run, because a malformed reply must never read as "no findings",
40
- * and so does any other top-level key, because text planted in an unescaped string could close
39
+ * non-array `findings` is a failed reply, which fails a gating profile's review and is an advisory
40
+ * profile's `research-failed` gap, because a malformed reply must never read as "no findings", and so
41
+ * is any other top-level key, because text planted in an unescaped string could close
41
42
  * the findings array early and move the rest of the reply under a key of its own, where it would
42
43
  * be dropped without a trace. Only the first `limit` listed findings are read, so a flooded reply
43
44
  * costs bounded work; each of those that does not match the schema, or holds a nested object or
@@ -109,8 +109,9 @@ function syntaxAfterAnswer(visible, first, copies) {
109
109
  }
110
110
  /**
111
111
  * Validate a research reply. The envelope must be exactly `{ findings: [...] }`: a missing or
112
- * non-array `findings` fails the run, because a malformed reply must never read as "no findings",
113
- * and so does any other top-level key, because text planted in an unescaped string could close
112
+ * non-array `findings` is a failed reply, which fails a gating profile's review and is an advisory
113
+ * profile's `research-failed` gap, because a malformed reply must never read as "no findings", and so
114
+ * is any other top-level key, because text planted in an unescaped string could close
114
115
  * the findings array early and move the rest of the reply under a key of its own, where it would
115
116
  * be dropped without a trace. Only the first `limit` listed findings are read, so a flooded reply
116
117
  * costs bounded work; each of those that does not match the schema, or holds a nested object or
@@ -14,6 +14,7 @@ export interface CompletionRequest {
14
14
  name: string;
15
15
  schema: JsonSchema;
16
16
  };
17
+ /** The attempt's own signal: aborted with the review's, or at the attempt's deadline. */
17
18
  signal?: AbortSignal;
18
19
  }
19
20
  /**
@@ -26,6 +27,34 @@ export interface CompletionResponse {
26
27
  model: string;
27
28
  usage?: Usage;
28
29
  }
30
+ /** The deadline of an attempt when its provider states none: ten minutes. */
31
+ export declare const DEFAULT_TIMEOUT_MS = 600000;
32
+ /** The shortest deadline: one second. */
33
+ export declare const MIN_TIMEOUT_MS = 1000;
34
+ /** The longest deadline an option, a config or a variable sets: 24 hours. */
35
+ export declare const MAX_TIMEOUT_MS = 86400000;
36
+ /** The most retries a call is given. */
37
+ export declare const MAX_RETRIES = 5;
38
+ /**
39
+ * The retries a shipped adapter states when its options set none: two. A provider that states none
40
+ * gets no retry, since the core must not retry what may retry by itself.
41
+ */
42
+ export declare const DEFAULT_RETRIES = 2;
43
+ /**
44
+ * The longest deadline a provider states: six times `MAX_TIMEOUT_MS`, since a provider that runs
45
+ * the retries itself states the deadline of its whole call, `timeoutMs` times `MAX_RETRIES + 1`.
46
+ */
47
+ export declare const MAX_STATED_TIMEOUT_MS: number;
48
+ /**
49
+ * What is wrong with a deadline, worded with what to write, or undefined for a safe integer from
50
+ * `MIN_TIMEOUT_MS` to `max`. The value is never quoted: it may be anything.
51
+ */
52
+ export declare function timeoutProblem(value: unknown, max?: number): string | undefined;
53
+ /**
54
+ * What is wrong with a count of retries, worded with what to write, or undefined for a whole number
55
+ * from 0 to `MAX_RETRIES`. The value is never quoted: it may be anything.
56
+ */
57
+ export declare function retriesProblem(value: unknown): string | undefined;
29
58
  /**
30
59
  * A model behind a port: it receives text and returns text (invariant I1). No environment value, key
31
60
  * or credential appears in a request; keys live in adapters only. The core never trusts the reply
@@ -34,10 +63,36 @@ export interface CompletionResponse {
34
63
  export interface Provider {
35
64
  readonly id: string;
36
65
  readonly model: string;
66
+ /**
67
+ * The deadline of one attempt, in whole milliseconds from 1000 to 518400000; `DEFAULT_TIMEOUT_MS`
68
+ * when unset. At it the core aborts the attempt's signal and fails the attempt as a timeout,
69
+ * whatever the provider does. It is read when the quorum is created, as an own data
70
+ * property: a getter is never run and an inherited property states nothing, so a class sets it as
71
+ * a field.
72
+ */
73
+ readonly timeoutMs?: number;
74
+ /**
75
+ * How often the core retries a call that failed in passing, after its first attempt: a whole
76
+ * number from 0 to 5; none when unset, since a provider that retries by itself must not be
77
+ * retried again. The core retries only a `network`, `timeout` or `http` failure that says it may
78
+ * be retried, and never a call's second timeout. It is read when the quorum is created, as
79
+ * an own data property, as `timeoutMs` is.
80
+ */
81
+ readonly retries?: number;
82
+ /**
83
+ * The most tokens, input and output, that one attempt of `request` may spend as the provider is billed
84
+ * for it, which is what the core reserves for each attempt of the request. It is called once per call,
85
+ * once the request is built; a result that is not a whole number of at least 1, or a throw, states
86
+ * nothing, and the core then reserves its own count of the request plus 512 tokens for what a server
87
+ * adds and 16000 for the reply, as it does when this is unset. It is read when the quorum is created,
88
+ * as an own data property, as `timeoutMs` is: a getter is never run and an inherited method states
89
+ * nothing, so a class sets it as an arrow-function field.
90
+ */
91
+ readonly worstCase?: (request: CompletionRequest) => number;
37
92
  /**
38
93
  * Answer one request. It should honour `request.signal`, settling soon after the signal aborts:
39
- * stopping a call in flight is cooperative, so a review can wait for a call it cut until the
40
- * provider settles.
94
+ * the core settles the call at its deadline or at the review's abort without waiting for the
95
+ * provider, and a provider that ignores the signal works on, outside the review, until it ends.
41
96
  */
42
97
  complete: (request: CompletionRequest) => Promise<CompletionResponse>;
43
98
  }
@@ -1 +1,36 @@
1
- export {};
1
+ /** The deadline of an attempt when its provider states none: ten minutes. */
2
+ export const DEFAULT_TIMEOUT_MS = 600_000;
3
+ /** The shortest deadline: one second. */
4
+ export const MIN_TIMEOUT_MS = 1000;
5
+ /** The longest deadline an option, a config or a variable sets: 24 hours. */
6
+ export const MAX_TIMEOUT_MS = 86_400_000;
7
+ /** The most retries a call is given. */
8
+ export const MAX_RETRIES = 5;
9
+ /**
10
+ * The retries a shipped adapter states when its options set none: two. A provider that states none
11
+ * gets no retry, since the core must not retry what may retry by itself.
12
+ */
13
+ export const DEFAULT_RETRIES = 2;
14
+ /**
15
+ * The longest deadline a provider states: six times `MAX_TIMEOUT_MS`, since a provider that runs
16
+ * the retries itself states the deadline of its whole call, `timeoutMs` times `MAX_RETRIES + 1`.
17
+ */
18
+ export const MAX_STATED_TIMEOUT_MS = MAX_TIMEOUT_MS * (MAX_RETRIES + 1);
19
+ /**
20
+ * What is wrong with a deadline, worded with what to write, or undefined for a safe integer from
21
+ * `MIN_TIMEOUT_MS` to `max`. The value is never quoted: it may be anything.
22
+ */
23
+ export function timeoutProblem(value, max = MAX_TIMEOUT_MS) {
24
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= MIN_TIMEOUT_MS && value <= max
25
+ ? undefined
26
+ : `must be a whole number of milliseconds from ${MIN_TIMEOUT_MS} to ${max}`;
27
+ }
28
+ /**
29
+ * What is wrong with a count of retries, worded with what to write, or undefined for a whole number
30
+ * from 0 to `MAX_RETRIES`. The value is never quoted: it may be anything.
31
+ */
32
+ export function retriesProblem(value) {
33
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_RETRIES
34
+ ? undefined
35
+ : `must be a whole number from 0 to ${MAX_RETRIES}`;
36
+ }
@@ -1,3 +1,4 @@
1
+ import type { Clock } from './clock.ts';
1
2
  import type { QuorumPorts } from './ports.ts';
2
3
  import type { Quorum, QuorumOptions } from './types.ts';
3
4
  /**
@@ -7,16 +8,23 @@ import type { Quorum, QuorumOptions } from './types.ts';
7
8
  * Every problem is reported at once, in one ConfigError, never as a TypeError, so an untyped caller
8
9
  * gets the checks a config file gets: options and ports that are not objects, no profile, each
9
10
  * profile's own issues, a repeated profile id, a `concurrency` or `maxFindings` that is not a
10
- * positive integer, a missing or malformed research provider or voter, ports for a profile or a
11
- * lens the run does not have (a likely typo), and an event sink that is not a function. Ports are
12
- * checked only for the profiles that have no issue of their own, and not at all when `profiles` is
13
- * not an array. Every record keyed by a caller's id is read as an own property, since `constructor`
14
- * is a valid id.
11
+ * positive integer, a `maxReviewTokens` that is not a whole number of tokens from 1 to
12
+ * 9007199254740991, a `reviewTimeoutMs` that is not a whole number of milliseconds from 1000 to
13
+ * 86400000, an `exclude` that is not a list of at most 100 patterns that can be taken, a
14
+ * missing or malformed research provider or voter, a provider's stated `timeoutMs` that is not a
15
+ * whole number of milliseconds from 1000 to 518400000, `retries` that is not a whole number from
16
+ * 0 to 5 or `worstCase` that is not a function, ports for a profile or a lens the run does not have
17
+ * (a likely typo), and an event sink that is not a function. Ports are checked only for the profiles
18
+ * that have no issue of their own, and not at all when `profiles` is not an array. Every record keyed
19
+ * by a caller's id is read as an own property, since `constructor` is a valid id. `maxReviewTokens`,
20
+ * the most tokens one review spends, input and output, is 2000000 when unset, and `reviewTimeoutMs`,
21
+ * how long one review runs, is 1800000 (30 minutes) when unset: see `review`.
15
22
  *
16
23
  * Each profile is compiled into a frozen `ProfileRun`, its instructions rendered, its thresholds
17
- * resolved and its providers captured, so later changes to the caller's profiles or ports are not
18
- * seen. `warnings` lists what the profiles set that cannot take full effect. Each review can be
19
- * stopped through its own signal; a throwing event sink or a failing profile stops it too.
24
+ * resolved and its providers captured, and `exclude` is compiled into a matcher, so later changes to
25
+ * the caller's profiles, ports or `exclude` are not seen. `warnings` lists what the profiles set
26
+ * that cannot take full effect. Each review can be stopped through its own signal; a throwing event
27
+ * sink or a failing profile stops it too.
20
28
  *
21
29
  * @throws ConfigError listing every issue of the options and the ports
22
30
  *
@@ -26,3 +34,11 @@ import type { Quorum, QuorumOptions } from './types.ts';
26
34
  * const { kept, meta } = await quorum.review({ diff: diffText }, { signal: controller.signal })
27
35
  */
28
36
  export declare function createQuorum(options: QuorumOptions, ports: QuorumPorts): Quorum;
37
+ /**
38
+ * `createQuorum` on a clock of the caller's: the time, the randomness and the one timer the call path and the
39
+ * review's deadline read. It is the specs' seam, so a review's deadline and a call's waits run on a fake clock
40
+ * and cost no real time; the package does not export it, and `createQuorum` passes the system's clock.
41
+ *
42
+ * @throws ConfigError listing every issue of the options and the ports, as `createQuorum` does
43
+ */
44
+ export declare function createQuorumWith(options: QuorumOptions, ports: QuorumPorts, clock: Clock): Quorum;