@4fu/arbor-judge-jev 0.0.0-stage → 0.1.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.
package/jev.js ADDED
@@ -0,0 +1,233 @@
1
+ /**
2
+ * Jev, the default `Judge` (docs/dispatch.md#judge-decisions).
3
+ *
4
+ * Jev is TypeSafe AI's System One classifier: `POST {base}/systemone` with one
5
+ * JSON state and several typed questions about it, and one answer per question,
6
+ * each with its score or probability. It answers the host's decisions - filter,
7
+ * route, model tier, notice, broadcast, active set - one request per decision
8
+ * with its questions batched, and it decides whether, where and when. It never
9
+ * writes text; the model owns content.
10
+ *
11
+ * This wrapper owns four things and nothing else:
12
+ *
13
+ * 1. **One request per decision.** `decide` builds the decision's questions
14
+ * and its state (questions.ts), scrubs both (scrub.ts), posts them once
15
+ * (wire.ts) and reads the answers back into the core's own shapes.
16
+ * 2. **Scrubbing on the way out.** Every string of the state and of the
17
+ * questions goes through `scrub` before it leaves the host, and the decision
18
+ * log records the scrubbed form, so a secret value reaches neither Jev nor
19
+ * the log (docs/dispatch.md#judge-decisions).
20
+ * 3. **Every answer with its scores.** `onDecision` is called once per decision
21
+ * with the state the judge saw, the questions, every answer with its score
22
+ * or probability, the token usage and how long it took, so the host logs
23
+ * them and tunes its thresholds from real decisions.
24
+ * 4. **Refusing, not guessing.** A missing key, a transport failure or an
25
+ * answer of the wrong shape raises the core's `unavailable` error naming the
26
+ * rule and the next action. It never fabricates an answer: the rule bounds
27
+ * and the fallbacks live in the service layer, so an unreachable judge
28
+ * changes nothing about the rules (packages/interfaces/src/judge.ts).
29
+ *
30
+ * What it does not own: the rule bounds and the fallbacks around a decision.
31
+ * The judge answers what it is asked, in `shadow` exactly as in `on`, and the
32
+ * mode rides on the decision log. A decision that is `off` asks nothing at all
33
+ * and is answered with that decision's own documented default
34
+ * (docs/dispatch.md#judge-decisions), so it costs no request.
35
+ */
36
+ import { arborError } from "@4fu/arbor-errors";
37
+ import { resolveJevOptions } from "./options.js";
38
+ import { activeSetAnswer, broadcastAnswer, filterAnswer, modelTierAnswer, noticeAnswer, prepareActiveSet, prepareBroadcast, prepareFilter, prepareModelTier, prepareNotice, prepareRoute, routeAnswer, } from "./questions.js";
39
+ import { scrubJson, scrubQuestions } from "./scrub.js";
40
+ import { fromWireAnswer, toWireQuestion } from "./wire.js";
41
+ /** The rule every refusal of this package names. */
42
+ const UNAVAILABLE_RULE = "judge.jev.unreachable";
43
+ /** The next action every refusal of this package names. */
44
+ const UNAVAILABLE_ACTION = "the service layer applies this decision's rule fallback (docs/dispatch.md#judge-decisions)";
45
+ export class Jev {
46
+ name = "jev";
47
+ options;
48
+ constructor(options = {}) {
49
+ this.options = resolveJevOptions(options);
50
+ }
51
+ /** Answer one decision. One request, with that decision's questions batched. */
52
+ async decide(request) {
53
+ switch (request.decision) {
54
+ case "filter":
55
+ return this.filter(request);
56
+ case "route":
57
+ return this.route(request);
58
+ case "model_tier":
59
+ return this.modelTier(request);
60
+ case "notice":
61
+ return this.notice(request);
62
+ case "broadcast":
63
+ return this.broadcast(request);
64
+ case "active_set":
65
+ return this.activeSet(request);
66
+ }
67
+ }
68
+ async filter(request) {
69
+ const { answers } = await this.run(request, prepareFilter(request.state, request.criteria ?? []));
70
+ return filterAnswer(answers, this.options.thresholds.filter);
71
+ }
72
+ async route(request) {
73
+ const prepared = prepareRoute(request.state, this.options.maxItems, request.criteria ?? []);
74
+ const { answers, asked } = await this.run(request, prepared);
75
+ return routeAnswer(answers, asked, request.state.candidates);
76
+ }
77
+ async modelTier(request) {
78
+ const prepared = prepareModelTier(request.state, request.criteria ?? [], this.options.tierCriteria);
79
+ const { answers } = await this.run(request, prepared);
80
+ return modelTierAnswer(answers, request.state.tiers);
81
+ }
82
+ async notice(request) {
83
+ const prepared = prepareNotice(request.state, this.options.maxItems, request.criteria ?? []);
84
+ const { answers, asked } = await this.run(request, prepared);
85
+ return noticeAnswer(answers, request.state, asked, this.options.thresholds.notice);
86
+ }
87
+ async broadcast(request) {
88
+ const prepared = prepareBroadcast(request.state, this.options.maxItems, request.criteria ?? []);
89
+ // An environment delta is never filtered (docs/dispatch.md#judge-decisions):
90
+ // every window needs it, so there is nothing to ask about and no request is
91
+ // made. The decision is still logged, with the state and why it was skipped.
92
+ const unfiltered = request.state.unfiltered === true;
93
+ const { answers, asked } = await this.run(request, unfiltered ? { ...prepared, questions: {} } : prepared, unfiltered ? "unfiltered" : "no_items");
94
+ return broadcastAnswer(answers, request.state, asked, this.options.thresholds.broadcast);
95
+ }
96
+ async activeSet(request) {
97
+ const prepared = prepareActiveSet(request.state, this.options.maxItems, request.criteria ?? []);
98
+ const { answers, asked } = await this.run(request, prepared);
99
+ return activeSetAnswer(answers, request.state, asked, this.options.thresholds.activeSet);
100
+ }
101
+ /**
102
+ * Posts one decision and reads its answers back. The state and the questions
103
+ * are scrubbed once, here, on the way out, and the scrubbed forms are what the
104
+ * decision log records.
105
+ */
106
+ async run(request, prepared, skipped = "no_items") {
107
+ const scrub = this.options.scrub;
108
+ const state = scrub === undefined ? prepared.state : scrubJson(prepared.state, scrub);
109
+ const questions = scrub === undefined ? prepared.questions : scrubQuestions(prepared.questions, scrub);
110
+ const started = this.options.now();
111
+ const finish = (outcome, asked) => {
112
+ this.log(request, { state, questions, ...outcome, durationMs: this.options.now() - started });
113
+ if (!outcome.ok || outcome.answers === null) {
114
+ throw arborError({
115
+ code: "unavailable",
116
+ rule: UNAVAILABLE_RULE,
117
+ message: outcome.error ?? "Jev did not answer",
118
+ nextAction: UNAVAILABLE_ACTION,
119
+ });
120
+ }
121
+ return { answers: outcome.answers, asked };
122
+ };
123
+ // `off`: the decision acts on nothing, so nothing is asked and no request is
124
+ // made. Every answer below falls back to its own default, which is the same
125
+ // default the service layer applies (docs/dispatch.md#judge-decisions).
126
+ if (request.mode === "off") {
127
+ return finish({ answers: {}, ok: true, skipped: "off" }, []);
128
+ }
129
+ // Nothing to ask about: an unfiltered broadcast, no candidates, or no
130
+ // configured tiers. The decision is logged as skipped and every answer
131
+ // falls back to its own default.
132
+ if (Object.keys(questions).length === 0) {
133
+ return finish({ answers: {}, ok: true, skipped }, []);
134
+ }
135
+ try {
136
+ const response = await this.post({ model: this.options.modelId, state, questions });
137
+ const answers = {};
138
+ for (const [id, question] of Object.entries(questions)) {
139
+ const answer = response.answers[id];
140
+ if (answer === undefined)
141
+ continue;
142
+ answers[id] = fromWireAnswer(id, question, answer);
143
+ }
144
+ const outcome = {
145
+ answers,
146
+ ok: true,
147
+ ...(response.usage === undefined ? {} : { usage: response.usage }),
148
+ };
149
+ return finish(outcome, prepared.items);
150
+ }
151
+ catch (error) {
152
+ return finish({
153
+ answers: null,
154
+ ok: false,
155
+ error: error instanceof Error ? error.message : String(error),
156
+ }, []);
157
+ }
158
+ }
159
+ /** One System One request, with the bearer key read per call. */
160
+ async post(body) {
161
+ const apiKey = this.options.getApiKey();
162
+ if (apiKey === undefined || apiKey === "") {
163
+ throw arborError({
164
+ code: "unavailable",
165
+ rule: UNAVAILABLE_RULE,
166
+ message: `the Jev API key is not configured: set ${this.options.apiKeyEnv}`,
167
+ nextAction: UNAVAILABLE_ACTION,
168
+ });
169
+ }
170
+ const wire = {
171
+ model: body.model,
172
+ state: body.state,
173
+ questions: Object.fromEntries(Object.entries(body.questions).map(([id, question]) => [id, toWireQuestion(question)])),
174
+ };
175
+ const response = await this.options.fetchImpl(`${this.options.baseUrl.replace(/\/+$/u, "")}/systemone`, {
176
+ method: "POST",
177
+ headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
178
+ body: JSON.stringify(wire),
179
+ signal: AbortSignal.timeout(this.options.timeoutMs),
180
+ });
181
+ if (!response.ok) {
182
+ throw arborError({
183
+ code: "unavailable",
184
+ rule: UNAVAILABLE_RULE,
185
+ message: `Jev returned ${response.status}`,
186
+ nextAction: UNAVAILABLE_ACTION,
187
+ details: { status: response.status },
188
+ });
189
+ }
190
+ const parsed = parseWireResponse(await response.json());
191
+ if (parsed === undefined) {
192
+ throw arborError({
193
+ code: "unavailable",
194
+ rule: UNAVAILABLE_RULE,
195
+ message: "Jev returned a response this package cannot read",
196
+ nextAction: UNAVAILABLE_ACTION,
197
+ });
198
+ }
199
+ return parsed;
200
+ }
201
+ /** The decision log record, handed to the host for its own journal. */
202
+ log(request, record) {
203
+ this.options.onDecision?.({ decision: request.decision, mode: request.mode, ...record });
204
+ }
205
+ }
206
+ /** True when an error is a refusal of this package: the judge could not answer. */
207
+ export function isJevUnavailable(error) {
208
+ if (typeof error !== "object" || error === null)
209
+ return false;
210
+ const candidate = error;
211
+ return (candidate.code === "unavailable" &&
212
+ typeof candidate.rule === "string" &&
213
+ candidate.rule.startsWith("judge.jev."));
214
+ }
215
+ /** The response body, or undefined when it is not one this package can read. */
216
+ function parseWireResponse(json) {
217
+ if (typeof json !== "object" || json === null)
218
+ return undefined;
219
+ const answers = json.answers;
220
+ if (typeof answers !== "object" || answers === null)
221
+ return undefined;
222
+ const usage = json.usage;
223
+ const tokens = typeof usage === "object" && usage !== null
224
+ ? {
225
+ input: numberOr(usage.input_tokens),
226
+ output: numberOr(usage.output_tokens),
227
+ }
228
+ : undefined;
229
+ return { answers: answers, ...(tokens === undefined ? {} : { usage: tokens }) };
230
+ }
231
+ function numberOr(value) {
232
+ return typeof value === "number" && Number.isFinite(value) ? value : 0;
233
+ }
package/options.d.ts ADDED
@@ -0,0 +1,160 @@
1
+ /**
2
+ * What a deployment configures for Jev, the default `Judge`
3
+ * (docs/dispatch.md#judge-decisions, docs/architecture.md#interfaces).
4
+ *
5
+ * Jev is TypeSafe AI's System One classifier: one request carries one state and
6
+ * several typed questions about it, and every answer comes back with its score
7
+ * or its probability. It is not a chat model and not a pi provider: it is
8
+ * reached over HTTP with a bearer key, so this package holds no model catalog
9
+ * of its own and adds no dependency on the agent backend.
10
+ *
11
+ * A setting here names a secret and never holds its value
12
+ * (docs/architecture.md#data-placement): `apiKeyEnv` is the name of the
13
+ * environment variable the key is read from, per request, so a key that
14
+ * appears later applies to the next decision with no restart.
15
+ *
16
+ * What is *not* here: the rule bounds and the fallbacks. Those live in the
17
+ * service layer, in code that never moves, so an unreachable judge changes
18
+ * nothing about the rules (packages/interfaces/src/judge.ts). This package
19
+ * answers what it is asked, in every mode, and raises the core's
20
+ * `unavailable` error when it cannot.
21
+ */
22
+ import type { JudgeDecisionKind, JudgeMode } from "@4fu/arbor-interfaces";
23
+ /** The classifier model, and the service that serves it. */
24
+ export declare const JEV_MODEL_ID = "jev-latest";
25
+ /** TypeSafe's System One endpoint, under the versioned base URL. */
26
+ export declare const JEV_BASE_URL = "https://api.typesafe.ai/v1";
27
+ /** The environment variable naming the Jev API key. Never its value. */
28
+ export declare const JEV_API_KEY_ENV = "JEV_API_KEY";
29
+ /** How long one request may take before it is abandoned. 8 s. */
30
+ export declare const DEFAULT_TIMEOUT_MS = 8000;
31
+ /**
32
+ * How many items one request may ask about: candidate windows for `route`,
33
+ * `notice` and `broadcast`, notes for `active set`. The host's own bound is at
34
+ * most 8 route candidates (docs/dispatch.md#routing); this one keeps a state
35
+ * that ignored it inside Jev's context window.
36
+ */
37
+ export declare const DEFAULT_MAX_ITEMS = 8;
38
+ /** Where a bool answer's probability, or a score answer's level, turns into a yes. */
39
+ export interface JevThresholds {
40
+ filter?: number;
41
+ notice?: number;
42
+ broadcast?: number;
43
+ activeSet?: number;
44
+ }
45
+ /** What a tier is for, as the `model tier` question reads it. */
46
+ export declare const DEFAULT_TIER_CRITERIA: Record<string, string>;
47
+ export interface JevOptions {
48
+ /** The environment variable naming the API key. `JEV_API_KEY`. */
49
+ apiKeyEnv?: string;
50
+ /** Where the key comes from when not the environment: a secret store, a console field. */
51
+ getApiKey?: () => string | undefined;
52
+ /** The classifier model id. `jev-latest`. */
53
+ modelId?: string;
54
+ /** The service base URL. `https://api.typesafe.ai/v1`. */
55
+ baseUrl?: string;
56
+ /** How long one request may take. 8 s. */
57
+ timeoutMs?: number;
58
+ /** How many items one request may ask about. 8. */
59
+ maxItems?: number;
60
+ /**
61
+ * Where each decision reads its own answer. 0.5 everywhere: the classifier's
62
+ * own probability is the answer, and a deployment that wants a decision to
63
+ * fire more or less rarely moves it. The service layer's rule bounds and its
64
+ * fallback when the judge is unreachable still surround every decision.
65
+ */
66
+ thresholds?: JevThresholds;
67
+ /**
68
+ * What each configured tier is for, as the `model tier` question reads it.
69
+ * These are this package's own descriptions of the tiers it knows; what the
70
+ * host's `settings.judge.tierCriteria` says about a tier comes first, so a
71
+ * deployment whose tiers are not these describes them itself.
72
+ */
73
+ tierCriteria?: Record<string, string>;
74
+ /** Replaces `fetch`; tests pass a fake one, so no key and no network are needed. */
75
+ fetchImpl?: typeof fetch;
76
+ /**
77
+ * Scrubs secret values out of every request on the way out. Every string of
78
+ * the state and of the questions goes through it, and the decision log
79
+ * records the scrubbed form, so a secret value never reaches Jev and never
80
+ * reaches the log either.
81
+ */
82
+ scrub?: (text: string) => string;
83
+ /** Every decision, with its scores and the state the judge saw, for the host to log. */
84
+ onDecision?: (log: JevDecisionLog) => void;
85
+ /** The clock. Tests pass a fixed one. */
86
+ now?: () => number;
87
+ }
88
+ /** Every setting resolved to the value this package uses. */
89
+ export interface ResolvedJevOptions {
90
+ apiKeyEnv: string;
91
+ getApiKey: () => string | undefined;
92
+ modelId: string;
93
+ baseUrl: string;
94
+ timeoutMs: number;
95
+ maxItems: number;
96
+ thresholds: Required<JevThresholds>;
97
+ tierCriteria: Record<string, string>;
98
+ fetchImpl: typeof fetch;
99
+ scrub: ((text: string) => string) | undefined;
100
+ onDecision: ((log: JevDecisionLog) => void) | undefined;
101
+ now: () => number;
102
+ }
103
+ /**
104
+ * One judge request as it was sent: the decision, the mode it was asked in, the
105
+ * state and the questions after scrubbing, every answer with its score or
106
+ * probability, and how long it took. The host logs this record, so a threshold
107
+ * can be tuned from what the judge actually saw
108
+ * (docs/dispatch.md#judge-decisions).
109
+ */
110
+ export interface JevDecisionLog {
111
+ decision: JudgeDecisionKind;
112
+ mode: JudgeMode;
113
+ /** The state the judge saw, scrubbed. */
114
+ state: Record<string, unknown>;
115
+ /** The questions asked, scrubbed. */
116
+ questions: Record<string, JudgeQuestion>;
117
+ /** Every answer with its score or probability; null when the request failed. */
118
+ answers: Record<string, JudgeAnswerValue> | null;
119
+ ok: boolean;
120
+ error?: string;
121
+ durationMs: number;
122
+ /** Token usage the service reported, when it did. */
123
+ usage?: {
124
+ input: number;
125
+ output: number;
126
+ };
127
+ /** Why no request was made: `no_items` or `unfiltered`. */
128
+ skipped?: string;
129
+ }
130
+ /** A bool question: yes and no, both described. */
131
+ export interface BoolQuestion {
132
+ type: "bool";
133
+ instructions: string;
134
+ yes: string;
135
+ no: string;
136
+ }
137
+ /** A score question: one criterion per level, weakest first. */
138
+ export interface ScoreQuestion {
139
+ type: "score";
140
+ instructions: string;
141
+ levels: readonly string[];
142
+ }
143
+ /** A choice question: one criterion per option, keyed by the option's name. */
144
+ export interface ChoiceQuestion {
145
+ type: "choice";
146
+ instructions: string;
147
+ options: Record<string, string>;
148
+ }
149
+ export type JudgeQuestion = BoolQuestion | ScoreQuestion | ChoiceQuestion;
150
+ export type JudgeAnswerValue = {
151
+ type: "bool";
152
+ probability: number;
153
+ } | {
154
+ type: "score";
155
+ score: number;
156
+ } | {
157
+ type: "choice";
158
+ choice: string;
159
+ };
160
+ export declare function resolveJevOptions(options?: JevOptions): ResolvedJevOptions;
package/options.js ADDED
@@ -0,0 +1,63 @@
1
+ /**
2
+ * What a deployment configures for Jev, the default `Judge`
3
+ * (docs/dispatch.md#judge-decisions, docs/architecture.md#interfaces).
4
+ *
5
+ * Jev is TypeSafe AI's System One classifier: one request carries one state and
6
+ * several typed questions about it, and every answer comes back with its score
7
+ * or its probability. It is not a chat model and not a pi provider: it is
8
+ * reached over HTTP with a bearer key, so this package holds no model catalog
9
+ * of its own and adds no dependency on the agent backend.
10
+ *
11
+ * A setting here names a secret and never holds its value
12
+ * (docs/architecture.md#data-placement): `apiKeyEnv` is the name of the
13
+ * environment variable the key is read from, per request, so a key that
14
+ * appears later applies to the next decision with no restart.
15
+ *
16
+ * What is *not* here: the rule bounds and the fallbacks. Those live in the
17
+ * service layer, in code that never moves, so an unreachable judge changes
18
+ * nothing about the rules (packages/interfaces/src/judge.ts). This package
19
+ * answers what it is asked, in every mode, and raises the core's
20
+ * `unavailable` error when it cannot.
21
+ */
22
+ /** The classifier model, and the service that serves it. */
23
+ export const JEV_MODEL_ID = "jev-latest";
24
+ /** TypeSafe's System One endpoint, under the versioned base URL. */
25
+ export const JEV_BASE_URL = "https://api.typesafe.ai/v1";
26
+ /** The environment variable naming the Jev API key. Never its value. */
27
+ export const JEV_API_KEY_ENV = "JEV_API_KEY";
28
+ /** How long one request may take before it is abandoned. 8 s. */
29
+ export const DEFAULT_TIMEOUT_MS = 8_000;
30
+ /**
31
+ * How many items one request may ask about: candidate windows for `route`,
32
+ * `notice` and `broadcast`, notes for `active set`. The host's own bound is at
33
+ * most 8 route candidates (docs/dispatch.md#routing); this one keeps a state
34
+ * that ignored it inside Jev's context window.
35
+ */
36
+ export const DEFAULT_MAX_ITEMS = 8;
37
+ /** What a tier is for, as the `model tier` question reads it. */
38
+ export const DEFAULT_TIER_CRITERIA = {
39
+ light: "A short, conversational or routine task - answering, looking something up, summarising, a small edit - where a fast and cheap model is enough.",
40
+ strong: "A task that needs deep reasoning or long exact work - code, design, debugging, planning across many files - where a mistake is expensive.",
41
+ };
42
+ export function resolveJevOptions(options = {}) {
43
+ const thresholds = options.thresholds ?? {};
44
+ return {
45
+ apiKeyEnv: options.apiKeyEnv ?? JEV_API_KEY_ENV,
46
+ getApiKey: options.getApiKey ?? (() => process.env[options.apiKeyEnv ?? JEV_API_KEY_ENV]),
47
+ modelId: options.modelId ?? JEV_MODEL_ID,
48
+ baseUrl: options.baseUrl ?? JEV_BASE_URL,
49
+ timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
50
+ maxItems: options.maxItems ?? DEFAULT_MAX_ITEMS,
51
+ thresholds: {
52
+ filter: thresholds.filter ?? 0.5,
53
+ notice: thresholds.notice ?? 0.5,
54
+ broadcast: thresholds.broadcast ?? 0.5,
55
+ activeSet: thresholds.activeSet ?? 0.5,
56
+ },
57
+ tierCriteria: { ...DEFAULT_TIER_CRITERIA, ...(options.tierCriteria ?? {}) },
58
+ fetchImpl: options.fetchImpl ?? globalThis.fetch,
59
+ scrub: options.scrub,
60
+ onDecision: options.onDecision,
61
+ now: options.now ?? (() => Date.now()),
62
+ };
63
+ }
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@4fu/arbor-judge-jev",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "The default Judge: Jev, TypeSafe AI's System One classifier, answering filter, route, model tier, notice, broadcast and active set.",
6
+ "exports": {
7
+ ".": {
8
+ "types": "./index.d.ts",
9
+ "default": "./index.js"
10
+ }
11
+ },
12
+ "types": "./index.d.ts",
13
+ "main": "./index.js",
14
+ "files": [
15
+ "bounds.d.ts",
16
+ "bounds.js",
17
+ "index.d.ts",
18
+ "index.js",
19
+ "jev.d.ts",
20
+ "jev.js",
21
+ "options.d.ts",
22
+ "options.js",
23
+ "questions.d.ts",
24
+ "questions.js",
25
+ "scrub.d.ts",
26
+ "scrub.js",
27
+ "wire.d.ts",
28
+ "wire.js"
29
+ ],
30
+ "engines": {
31
+ "node": ">=24"
32
+ },
33
+ "license": "MIT",
34
+ "repository": {
35
+ "type": "git",
36
+ "url": "git+https://github.com/4fuu/arbor.git",
37
+ "directory": "packages/judge-jev"
38
+ },
39
+ "publishConfig": {
40
+ "access": "public"
41
+ },
42
+ "dependencies": {
43
+ "@4fu/arbor-errors": "0.1.0",
44
+ "@4fu/arbor-interfaces": "0.1.0"
45
+ }
46
+ }
package/questions.d.ts ADDED
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The six decisions of docs/dispatch.md#judge-decisions, as Jev questions.
3
+ *
4
+ * Each decision is one request with its questions batched: one bool question
5
+ * for `filter`, one score question per candidate window plus one for a new
6
+ * window for `route`, one choice question for `model tier`, one bool question
7
+ * per candidate window for `notice` and `broadcast`, and one score question
8
+ * per note for `active set`. When items fail separately there is one question
9
+ * per item - a window that does not need a notice is named, not averaged away
10
+ * (docs/prompting.md, "Batching").
11
+ *
12
+ * Every question follows docs/prompting.md, "Judge questions": the instruction
13
+ * names the state path it judges and the point of view and does not restate the
14
+ * state; the criteria describe both outcomes positively, with which evidence
15
+ * comes first, the boundary cases and a tie-break; counts, shares and time gaps
16
+ * are computed in code and appear as labelled facts, so Jev is asked for no
17
+ * arithmetic; and every state carries a `state_note` that defines each field.
18
+ * Questions are in English; the state keeps the original text as it is.
19
+ *
20
+ * The tie-break of every question leans toward the less harmful action, which
21
+ * is that decision's own documented fallback (docs/dispatch.md#judge-decisions):
22
+ * `filter` passes, `notice` stays silent, `broadcast` delivers, and `active set`
23
+ * leaves the rule score alone.
24
+ */
25
+ import type { ActiveSetAnswer, ActiveSetState, BroadcastAnswer, BroadcastState, CandidateWindow, FilterAnswer, FilterState, ModelTierAnswer, ModelTierState, NoticeAnswer, NoticeState, RouteAnswer, RouteState } from "@4fu/arbor-interfaces";
26
+ import type { JudgeAnswerValue, JudgeQuestion } from "./options.ts";
27
+ /** One decision, ready to send: its state, its questions and the items they judge. */
28
+ export interface PreparedDecision {
29
+ state: Record<string, unknown>;
30
+ questions: Record<string, JudgeQuestion>;
31
+ /** The items the questions were asked about, in the order they were asked. */
32
+ items: readonly string[];
33
+ }
34
+ /** `filter`: one bool question over the whole batch. */
35
+ export declare function prepareFilter(state: FilterState, criteria: readonly string[]): PreparedDecision;
36
+ /**
37
+ * `filter`'s answer. A question that was not answered at all is this decision's
38
+ * own fallback: the batch passes (docs/dispatch.md#judge-decisions). The
39
+ * probability rides along, because the threshold that turns it into a yes is the
40
+ * service layer's own.
41
+ */
42
+ export declare function filterAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, threshold: number): FilterAnswer;
43
+ /** `route`: one score question per candidate, and one for a new window. */
44
+ export declare function prepareRoute(state: RouteState, maxItems: number, criteria: readonly string[]): PreparedDecision;
45
+ /**
46
+ * `route`'s answer: every item's score, and the best of them. The best is the
47
+ * highest score among the items the request asked about; a tie keeps the
48
+ * earlier item, and a live window beats a new one, because opening one pays for
49
+ * a fresh prefix. A candidate the request could not ask about is scored 0 and is
50
+ * never the best, so a bounded request cannot be decided by what it left out.
51
+ * Whether the best is good enough to take the task is the host's own threshold
52
+ * (docs/dispatch.md#routing).
53
+ */
54
+ export declare function routeAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, asked: readonly string[], candidates: readonly CandidateWindow[]): RouteAnswer;
55
+ /** `model tier`: one choice question over the configured tiers. */
56
+ export declare function prepareModelTier(state: ModelTierState, criteria: readonly string[], tierCriteria: Record<string, string>): PreparedDecision;
57
+ /**
58
+ * `model tier`'s answer. A choice outside the configured tiers, or no answer at
59
+ * all, falls back to the first configured tier: only configured tiers are
60
+ * offered, and the host's own default tier is the rule default
61
+ * (docs/dispatch.md#judge-decisions).
62
+ */
63
+ export declare function modelTierAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, tiers: readonly string[]): ModelTierAnswer;
64
+ /** `notice`: one bool question per window that touched the event's target. */
65
+ export declare function prepareNotice(state: NoticeState, maxItems: number, criteria: readonly string[]): PreparedDecision;
66
+ /**
67
+ * `notice`'s answer: one decision per window the host passed. A window the
68
+ * request could not ask about, or one whose question was not answered, needs no
69
+ * notice, which is this decision's own fallback. The probability rides along for
70
+ * the service layer's own threshold.
71
+ */
72
+ export declare function noticeAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, state: NoticeState, asked: readonly string[], threshold: number): NoticeAnswer;
73
+ /** `broadcast`: one bool question per live window. */
74
+ export declare function prepareBroadcast(state: BroadcastState, maxItems: number, criteria: readonly string[]): PreparedDecision;
75
+ /**
76
+ * `broadcast`'s answer. A window the request could not ask about, or one whose
77
+ * question was not answered, needs the broadcast, which is this decision's own
78
+ * fallback: a delivery is never the harmful action
79
+ * (docs/dispatch.md#judge-decisions). The probability rides along for the
80
+ * service layer's own threshold.
81
+ */
82
+ export declare function broadcastAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, state: BroadcastState, asked: readonly string[], threshold: number): BroadcastAnswer;
83
+ /**
84
+ * `active set`: one score question per candidate note. The host's own order is
85
+ * not a ranking, so the candidates are ordered here by rule score, strongest
86
+ * first and ties by ref, which is the order the pick uses anyway; a note the
87
+ * request cannot ask about is left to the rule score alone.
88
+ */
89
+ export declare function prepareActiveSet(state: ActiveSetState, maxItems: number, criteria: readonly string[]): PreparedDecision;
90
+ /**
91
+ * `active set`'s answer: which notes are still needed, strongest first, and
92
+ * which are not. The judge's share is bounded by the host
93
+ * (docs/memory.md#the-active-set), so this is the judge's own reading and never
94
+ * the set itself. A note the request could not ask about, or one whose question
95
+ * was not answered, is left to the rule score alone, which is this decision's
96
+ * own fallback. Every note's level rides along, for the service layer's own
97
+ * threshold.
98
+ */
99
+ export declare function activeSetAnswer(answers: Readonly<Record<string, JudgeAnswerValue>>, state: ActiveSetState, asked: readonly string[], threshold: number): ActiveSetAnswer;