@niwa-labs/flow 0.0.0-stage → 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niwa Labs contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,31 @@
1
- # Temporary Holding Version
1
+ # @niwa-labs/flow
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Helpers for workflow scripts that need neither git nor processes: branch groups over `scope`, keyed maps, graphs, loops, `revise`, judging panels, verification and waiting on records or on the owner.
4
+
5
+ ```ts
6
+ import { revise, verify } from "@niwa-labs/flow";
7
+ ```
8
+
9
+ A helper runs inside a script on the script's own globals (`scope`, `agent`, `ask`, ...) and opens a
10
+ scope named by the key it is given; the calls it makes are keyed by their branch, never by a label,
11
+ so the same helper may run in every round of a loop. Keys of branches (items, nodes, briefs, seats)
12
+ are checked before anything runs.
13
+
14
+ - Groups: `parallel`, `map` (outcomes in the order of the items), `stream`, `firstPassing`, `rankAll`,
15
+ `mapReduce`, `swarm`, `consensus`.
16
+ - Order: `graph` (refuses missing nodes, repeated ids and cycles before it starts), `loop`, `saturate`,
17
+ `paramGrid` (a cell that failed has the score `null`).
18
+ - Quality: `revise`, `escalate`, `gate`, `verify`, `panel` (a judge that leaves a candidate unscored
19
+ has not answered). `INCONCLUSIVE` is never a pass.
20
+ - Waiting: `settle` (reads first, then waits for a record after what it read; `on` names its types
21
+ as text or by reference, and takes the query a plugin's builder gives; its `deadline` bounds the
22
+ waiting after the first reading, so the facts of a timed-out `settle` are never none), `humanGate` (a decline,
23
+ a cancel or a timeout is an outcome, never an error).
24
+
25
+ A failed branch is a value (`Settled`), except a refusal of the grant (`Denied`), a spent budget, or a
26
+ question to the owner that was cancelled or went unanswered (`AskCancelled`, `AskExpired`), which every
27
+ helper throws as soon as it is read; a worker that met one is not run again, and only `humanGate`
28
+ turns the last two into an outcome. The calls of a helper's callback that runs again (the attempts
29
+ of a `swarm` worker, the readings of `settle`) are keyed by the attempt (`a1`, `r1`), so a callback
30
+ may open a named scope each time. `Attempt(schema)` is the zod schema of what `revise` returns, for a
31
+ script's `output`.
package/package.json CHANGED
@@ -1,6 +1,16 @@
1
1
  {
2
2
  "name": "@niwa-labs/flow",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts"
8
+ },
9
+ "dependencies": {
10
+ "@niwa-labs/script": "0.0.0",
11
+ "zod": "^4.6.7"
12
+ },
13
+ "devDependencies": {
14
+ "@niwa-labs/testing": "0.0.0"
15
+ }
16
+ }
package/src/graph.ts ADDED
@@ -0,0 +1,115 @@
1
+ /**
2
+ * A graph of work: each node runs once every node it needs has succeeded, given their results.
3
+ *
4
+ * The graph is checked before anything runs: a node that needs a missing one, an id given twice
5
+ * and a cycle are refused. Nodes that become ready together start in the order of their ids, so
6
+ * a replay starts them in the same order whichever finished first.
7
+ */
8
+
9
+ import { checkKey, checkKeys, isFatal, script } from "./script.ts";
10
+ import type { Settled } from "./types.ts";
11
+
12
+ /** A node of a graph: its id, and the ids of the nodes it needs. */
13
+ export interface GraphNode {
14
+ id: string;
15
+ needs: string[];
16
+ }
17
+
18
+ /**
19
+ * The problems of a graph: missing nodes, ids given twice, and cycles. Empty when it can run.
20
+ * The cycle is named by its ids in the order they are met.
21
+ */
22
+ export function graphProblems(nodes: readonly GraphNode[]): string[] {
23
+ const problems: string[] = [];
24
+ const byId = new Map<string, GraphNode>();
25
+ for (const node of nodes) {
26
+ if (byId.has(node.id)) problems.push(`the node "${node.id}" is given twice`);
27
+ byId.set(node.id, node);
28
+ }
29
+ for (const node of nodes) {
30
+ for (const need of node.needs) if (!byId.has(need)) problems.push(`the node "${node.id}" needs "${need}", which is not in the graph`);
31
+ }
32
+ const state = new Map<string, "open" | "done">();
33
+ const walk = (id: string, path: string[]): void => {
34
+ if (state.get(id) === "done") return;
35
+ if (state.get(id) === "open") {
36
+ problems.push(`the nodes form a cycle: ${[...path.slice(path.indexOf(id)), id].join(" -> ")}`);
37
+ return;
38
+ }
39
+ state.set(id, "open");
40
+ for (const need of byId.get(id)?.needs ?? []) if (byId.has(need)) walk(need, [...path, id]);
41
+ state.set(id, "done");
42
+ };
43
+ for (const id of [...byId.keys()].sort()) walk(id, []);
44
+ return problems;
45
+ }
46
+
47
+ /**
48
+ * Run a graph. `onFail: "skip-descendants"` (the default) skips what depends on a failed node and
49
+ * runs the rest; `"stop"` cancels what is running and skips everything not started.
50
+ */
51
+ export async function graph<N extends GraphNode, R>(
52
+ key: string,
53
+ nodes: readonly N[],
54
+ opts: { concurrency?: number; run: (node: N, done: Record<string, R>) => Promise<R>; onFail?: "skip-descendants" | "stop" },
55
+ ): Promise<{ results: Record<string, Settled<R>>; skipped: string[] }> {
56
+ checkKey(key, "the key of a graph");
57
+ checkKeys(
58
+ nodes.map((node) => node.id),
59
+ "the id of a node",
60
+ );
61
+ const problems = graphProblems(nodes);
62
+ if (problems.length > 0) throw new TypeError(`graph "${key}": ${problems.join("; ")}`);
63
+ const onFail = opts.onFail ?? "skip-descendants";
64
+ const byId = new Map(nodes.map((node) => [node.id, node]));
65
+ const ids = [...byId.keys()].sort();
66
+
67
+ return script().scope(key, opts.concurrency === undefined ? undefined : { concurrency: opts.concurrency }, async (s) => {
68
+ // Ids are any keys a branch may have, `constructor` and `__proto__` among them: they are kept in maps, never as properties.
69
+ const results = new Map<string, Settled<R>>();
70
+ const done = new Map<string, R>();
71
+ const started = new Set<string>();
72
+ const skipped = new Set<string>();
73
+ let stopped = false;
74
+
75
+ const startReady = (): void => {
76
+ if (stopped) return;
77
+ for (const id of ids) {
78
+ if (started.has(id) || skipped.has(id)) continue;
79
+ const node = byId.get(id) as N;
80
+ if (!node.needs.every((need) => done.has(need))) continue;
81
+ started.add(id);
82
+ const given = Object.fromEntries(done) as Record<string, R>;
83
+ s.start(id, () => opts.run(node, given));
84
+ }
85
+ };
86
+ const skipBelow = (failed: string): void => {
87
+ for (let grew = true; grew; ) {
88
+ grew = false;
89
+ for (const id of ids) {
90
+ if (started.has(id) || skipped.has(id)) continue;
91
+ const node = byId.get(id) as N;
92
+ if (node.needs.some((need) => need === failed || skipped.has(need) || results.get(need)?.ok === false)) {
93
+ skipped.add(id);
94
+ grew = true;
95
+ }
96
+ }
97
+ }
98
+ };
99
+
100
+ startReady();
101
+ for (let got = await s.next(); got !== null; got = await s.next()) {
102
+ const settled = got.result as Settled<R>;
103
+ if (!settled.ok && isFatal(settled.error)) throw Object.assign(new Error(settled.error.message), { name: settled.error.name });
104
+ results.set(got.key, settled);
105
+ if (settled.ok) done.set(got.key, settled.value);
106
+ else if (onFail === "stop" && !stopped) {
107
+ stopped = true;
108
+ await s.cancel(`the node "${got.key}" failed`);
109
+ } else skipBelow(got.key);
110
+ startReady();
111
+ }
112
+ for (const id of ids) if (!started.has(id)) skipped.add(id);
113
+ return { results: Object.fromEntries(results) as Record<string, Settled<R>>, skipped: ids.filter((id) => skipped.has(id)) };
114
+ });
115
+ }
package/src/group.ts ADDED
@@ -0,0 +1,189 @@
1
+ /**
2
+ * Groups of branches over `scope`: a keyed map in the order of its input, a stream read in the
3
+ * order of outcomes and the two ways to choose from it, map-reduce in batches, a swarm of workers
4
+ * and a consensus of seats. A branch's failure is a value (`Settled`), except a refusal of the grant,
5
+ * a spent budget, or a question to the owner that was cancelled or went unanswered, which every
6
+ * helper throws the moment it is read.
7
+ */
8
+
9
+ import type { Stream } from "@niwa-labs/script";
10
+
11
+ import { sessionOptions, checkKey, checkKeys, errorOf, isFatal, script, seatKeys } from "./script.ts";
12
+ import type { Seat } from "./script.ts";
13
+ import type { Settled } from "./types.ts";
14
+
15
+ /** Branches at once by key, the answer in the same shape; a branch that fails cancels the others and its error is thrown. */
16
+ export function parallel<K extends string, T>(branches: Record<K, () => Promise<T>>, opts: { concurrency?: number } = {}): Promise<Record<K, T>> {
17
+ return script().parallel(branches, opts) as Promise<Record<K, T>>;
18
+ }
19
+
20
+ /**
21
+ * Run `fn` for every item, each in a branch keyed by `opts.key(item)`, at most `concurrency` at once.
22
+ * The outcomes come in the order of the items, whichever ended first.
23
+ */
24
+ export async function map<I, T>(
25
+ key: string,
26
+ items: readonly I[],
27
+ opts: { key: (item: I) => string; concurrency?: number },
28
+ fn: (item: I) => Promise<T>,
29
+ ): Promise<Settled<T>[]> {
30
+ checkKey(key, "the key of a map");
31
+ const keys = checkKeys(items.map(opts.key), "the key of an item");
32
+ return script().scope(key, opts.concurrency === undefined ? undefined : { concurrency: opts.concurrency }, async (s) => {
33
+ const branches = items.map((item, index) => s.start(keys[index] as string, () => fn(item)));
34
+ const at = new Map(keys.map((one, index) => [one, index]));
35
+ const out: Settled<T>[] = [];
36
+ // The outcomes are read as the host committed them, so an error that must leave is met when it ends, not when the branches before it have; they are put in the order of the items.
37
+ for (let got = await s.next(); got !== null; got = await s.next()) {
38
+ const index = at.get(got.key) as number;
39
+ const settled = got.result as Settled<T>;
40
+ if (!settled.ok && isFatal(settled.error)) {
41
+ // The original error leaves the map, and the scope cancels the rest.
42
+ await (branches[index] as { value(): Promise<T> }).value();
43
+ throw errorOf(settled);
44
+ }
45
+ out[index] = settled;
46
+ }
47
+ return out;
48
+ });
49
+ }
50
+
51
+ /**
52
+ * Branches read one outcome at a time, in the order the host committed them. Closing the stream
53
+ * cancels the rest. Every way to read it throws an error no helper keeps as a value (a refusal of
54
+ * the grant, a spent budget, an unanswered question), as `map` does.
55
+ */
56
+ export function stream<K extends string, T>(key: string, branches: Record<K, () => Promise<T>>, opts: { concurrency?: number } = {}): Stream<K, T> {
57
+ checkKey(key, "the key of a stream");
58
+ checkKeys(Object.keys(branches), "the key of a branch");
59
+ const raw = script().stream(key, branches, opts) as Stream<K, T>;
60
+ const checked = <V extends { result: Settled<T> }>(got: V): V => {
61
+ if (!got.result.ok && isFatal(got.result.error)) throw errorOf(got.result);
62
+ return got;
63
+ };
64
+ const checkedStream: Stream<K, T> = {
65
+ next: async () => {
66
+ const got = await raw.next();
67
+ return got === null ? null : checked(got);
68
+ },
69
+ ready: async () => (await raw.ready()).map(checked),
70
+ rest: async () => {
71
+ const all = await raw.rest();
72
+ for (const settled of Object.values<Settled<T>>(all)) checked({ result: settled });
73
+ return all;
74
+ },
75
+ pending: () => raw.pending(),
76
+ cancel: (keys) => raw.cancel(keys),
77
+ close: () => raw.close(),
78
+ async *[Symbol.asyncIterator]() {
79
+ for (let got = await checkedStream.next(); got !== null; got = await checkedStream.next()) yield got;
80
+ },
81
+ [Symbol.asyncDispose]: () => raw[Symbol.asyncDispose](),
82
+ };
83
+ return checkedStream;
84
+ }
85
+
86
+ /** The first outcome of a stream that succeeded and passes `pass`; the stream stays open. Null when none did. */
87
+ export async function firstPassing<K extends string, T>(s: Stream<K, T>, pass: (value: T) => boolean): Promise<{ key: K; value: T } | null> {
88
+ for (let got = await s.next(); got !== null; got = await s.next()) {
89
+ if (got.result.ok && pass(got.result.value)) return { key: got.key, value: got.result.value };
90
+ if (!got.result.ok && isFatal(got.result.error)) throw errorOf(got.result);
91
+ }
92
+ return null;
93
+ }
94
+
95
+ /** Every outcome of a stream, then the one `rank` picks. The pick must be a branch that succeeded. */
96
+ export async function rankAll<K extends string, T>(
97
+ s: Stream<K, T>,
98
+ rank: (all: Record<K, Settled<T>>) => Promise<K>,
99
+ ): Promise<{ key: K; value: T; all: Record<K, Settled<T>> }> {
100
+ const all = await s.rest();
101
+ for (const settled of Object.values<Settled<T>>(all)) if (!settled.ok && isFatal(settled.error)) throw errorOf(settled);
102
+ const key = await rank(all);
103
+ const picked = Object.hasOwn(all, key) ? all[key] : undefined;
104
+ if (picked === undefined) throw new Error(`rankAll: "${key}" is not a branch of the stream`);
105
+ if (!picked.ok) throw new Error(`rankAll: "${key}" failed (${picked.error.message}), it cannot be picked`);
106
+ return { key, value: picked.value, all };
107
+ }
108
+
109
+ /**
110
+ * Map items in batches of `batch` (8 by default) and reduce the outcomes. A batch is keyed by the
111
+ * key of its first item; the outcomes reach `reduce` in the order of the batches.
112
+ */
113
+ export async function mapReduce<I, M, R>(
114
+ key: string,
115
+ items: readonly I[],
116
+ opts: { batch?: number; key: (item: I) => string; map: (batch: I[]) => Promise<M>; reduce: (parts: Settled<M>[]) => Promise<R>; concurrency?: number },
117
+ ): Promise<R> {
118
+ checkKey(key, "the key of a map-reduce");
119
+ const size = opts.batch ?? 8;
120
+ if (!Number.isInteger(size) || size < 1) throw new TypeError(`mapReduce: a batch is a whole number of items, at least one, not ${String(size)}`);
121
+ checkKeys(items.map(opts.key), "the key of an item");
122
+ const batches: I[][] = [];
123
+ for (let at = 0; at < items.length; at += size) batches.push(items.slice(at, at + size));
124
+ return script().scope(key, undefined, async () => {
125
+ const parts = await map("map", batches, { key: (batch) => opts.key(batch[0] as I), ...(opts.concurrency === undefined ? {} : { concurrency: opts.concurrency }) }, opts.map);
126
+ return opts.reduce(parts);
127
+ });
128
+ }
129
+
130
+ /**
131
+ * Workers on briefs, each in a branch keyed by the brief's id, each attempt in a scope `a1`, `a2`
132
+ * of its own. A result `valid` refuses is dropped; with `respawn: 1` a worker that failed or was
133
+ * refused runs once more, unless it met an error no helper keeps as a value. `gaps` are the briefs with
134
+ * no result in the end, `dropped` those whose result was refused.
135
+ */
136
+ export async function swarm<B, R>(
137
+ key: string,
138
+ opts: { briefs: Record<string, B>; worker: (brief: B, id: string) => Promise<R>; valid?: (result: R, brief: B) => boolean; respawn?: 0 | 1; concurrency?: number },
139
+ ): Promise<{ results: Record<string, R>; gaps: string[]; dropped: string[] }> {
140
+ checkKey(key, "the key of a swarm");
141
+ const ids = checkKeys(Object.keys(opts.briefs), "the id of a brief");
142
+ const tries = 1 + (opts.respawn ?? 0);
143
+ const outcomes = await map(key, ids, { key: (id) => id, ...(opts.concurrency === undefined ? {} : { concurrency: opts.concurrency }) }, async (id) => {
144
+ const brief = opts.briefs[id] as B;
145
+ let refused = false;
146
+ for (let attempt = 1; attempt <= tries; attempt += 1) {
147
+ let result: R;
148
+ try {
149
+ // Each attempt is a scope of its own, so what the worker names in it is not met a second time.
150
+ result = await script().scope(`a${String(attempt)}`, undefined, () => opts.worker(brief, id));
151
+ } catch (error) {
152
+ if (error instanceof Error && isFatal(error)) throw error;
153
+ if (attempt === tries) throw error;
154
+ continue;
155
+ }
156
+ if (opts.valid === undefined || opts.valid(result, brief)) return { kept: true as const, result };
157
+ refused = true;
158
+ }
159
+ return { kept: false as const, refused };
160
+ });
161
+ const results = new Map<string, R>();
162
+ const gaps: string[] = [];
163
+ const dropped: string[] = [];
164
+ outcomes.forEach((outcome, index) => {
165
+ const id = ids[index] as string;
166
+ if (outcome.ok && outcome.value.kept) results.set(id, outcome.value.result);
167
+ else {
168
+ gaps.push(id);
169
+ if (outcome.ok && outcome.value.refused) dropped.push(id);
170
+ }
171
+ });
172
+ return { results: Object.fromEntries(results), gaps, dropped };
173
+ }
174
+
175
+ /** The same work on every seat, then `agree` on the values that came back: null when they do not agree. */
176
+ export async function consensus<T>(
177
+ key: string,
178
+ opts: { seats: readonly Seat[]; run: (seat: Seat) => Promise<T>; agree: (all: T[]) => T | null },
179
+ ): Promise<{ value: T | null; all: Settled<T>[] }> {
180
+ const keys = seatKeys(opts.seats, "the key of a seat");
181
+ const all = await map(key, opts.seats.map((seat, index) => ({ seat, key: keys[index] as string })), { key: (one) => one.key }, (one) => opts.run(one.seat));
182
+ const values = all.flatMap((settled) => (settled.ok ? [settled.value] : []));
183
+ return { value: values.length === 0 ? null : opts.agree(values), all };
184
+ }
185
+
186
+ /** Ask a seat with a schema: the call `ask()` makes for a seat. */
187
+ export function askSeat<T>(seat: Seat, prompt: string, schema: import("zod").z.ZodType<T>): Promise<T> {
188
+ return script().ask({ ...sessionOptions(seat), schema }, prompt) as Promise<T>;
189
+ }
package/src/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ // Helpers for workflow scripts that need neither git nor processes. Each runs inside a script, on
2
+ // its globals, and opens a scope named by the key it is given.
3
+
4
+ export { Attempt, FindingSchema, JudgedSchema, VERDICTS, VerdictSchema, passes } from "./types.ts";
5
+ export type { Finding, FlowError, Judged, Settled, Verdict } from "./types.ts";
6
+ export { sessionOptions, checkKey, checkKeys, harnessOf, isFatal, script, seatKeys, vendorOf, zod } from "./script.ts";
7
+ export type { ScriptGlobals, Seat, SeatOptions } from "./script.ts";
8
+ export { askSeat, consensus, firstPassing, map, mapReduce, parallel, rankAll, stream, swarm } from "./group.ts";
9
+ export { graph, graphProblems } from "./graph.ts";
10
+ export type { GraphNode } from "./graph.ts";
11
+ export { escalate, gridCells, loop, paramGrid, revise, saturate } from "./loop.ts";
12
+ export type { GridCell } from "./loop.ts";
13
+ export { GateFailed, blindLabel, decidePanel, gate, panel, tally, verify } from "./judge.ts";
14
+ export type { Band, PanelJudge, Require } from "./judge.ts";
15
+ export { humanGate, settle } from "./wait.ts";
package/src/judge.ts ADDED
@@ -0,0 +1,227 @@
1
+ /**
2
+ * Judging: a gate of one judge, verification by several seats and lenses, and a panel that scores
3
+ * candidates. A judge that fails to answer is an `INCONCLUSIVE` vote, never a pass, and a panel with
4
+ * no judge independent of the author decides nothing.
5
+ */
6
+
7
+ import { askSeat, map } from "./group.ts";
8
+ import { checkKey, harnessOf, isFatal, script, seatKeys, vendorOf } from "./script.ts";
9
+ import type { Seat } from "./script.ts";
10
+ import { VerdictSchema, passes } from "./types.ts";
11
+ import type { Finding, Judged, Verdict } from "./types.ts";
12
+
13
+ /** How many votes a verification needs to pass: every one, more than half, or at least a number. */
14
+ export type Require = "all" | "majority" | { atLeast: number };
15
+
16
+ /** A judgement that did not pass a gate. */
17
+ export class GateFailed extends Error {
18
+ override name = "GateFailed";
19
+ readonly judged: Judged;
20
+ constructor(subject: string, judged: Judged) {
21
+ super(`the gate on ${subject} did not pass: ${judged.verdict}${judged.findings.length === 0 ? "" : ` (${judged.findings.map((finding) => finding.title).join("; ")})`}`);
22
+ this.judged = judged;
23
+ }
24
+ }
25
+
26
+ /** The question put to a judge. */
27
+ function judgePrompt(subject: string, stance: "check" | "refute", lens: string | undefined): string {
28
+ return [
29
+ stance === "refute"
30
+ ? "Try to refute the claim below. Look for what makes it wrong; it passes only if you cannot."
31
+ : "Check the work below and judge whether it holds.",
32
+ ...(lens === undefined ? [] : [`Judge it through this lens only: ${lens}.`]),
33
+ "",
34
+ subject,
35
+ "",
36
+ "Answer with a verdict: PASS when it holds, PASS+NOTES when it holds and you have remarks, FAIL when it does not, " +
37
+ "INCONCLUSIVE when you cannot tell. List what you found, each with its evidence; a finding that must be fixed before the work is accepted blocks, any other is a note.",
38
+ ].join("\n");
39
+ }
40
+
41
+ /** Ask one seat to judge: what it answers, or an `INCONCLUSIVE` vote when it could not answer. */
42
+ async function judgeBy(seat: Seat, subject: string, stance: "check" | "refute", lens: string | undefined): Promise<Judged> {
43
+ const method = `${stance} by ${harnessOf(seat)}${lens === undefined ? "" : ` (${lens})`}`;
44
+ const answer = await askSeat(seat, judgePrompt(subject, stance, lens), VerdictSchema());
45
+ return { verdict: answer.verdict, findings: answer.findings, method };
46
+ }
47
+
48
+ /** How many votes are needed out of `n`. */
49
+ function needed(require: Require, n: number): number {
50
+ if (require === "all") return n;
51
+ if (require === "majority") return Math.floor(n / 2) + 1;
52
+ if (!Number.isInteger(require.atLeast) || require.atLeast < 1) throw new TypeError(`require.atLeast is a whole number, at least one, not ${String(require.atLeast)}`);
53
+ return require.atLeast;
54
+ }
55
+
56
+ /**
57
+ * The verdict of votes: a pass when enough votes pass (with notes when any passing vote has some), a
58
+ * fail when too many failed for that to happen, and `INCONCLUSIVE` otherwise or with no vote.
59
+ */
60
+ export function tally(votes: readonly Judged[], require: Require, method: string): Judged {
61
+ const findings: Finding[] = votes.flatMap((vote) => vote.findings);
62
+ if (votes.length === 0) return { verdict: "INCONCLUSIVE", findings, method };
63
+ const need = needed(require, votes.length);
64
+ const passing = votes.filter(passes);
65
+ const failing = votes.filter((vote) => vote.verdict === "FAIL").length;
66
+ let verdict: Verdict;
67
+ if (need > votes.length) verdict = "INCONCLUSIVE";
68
+ else if (passing.length >= need) verdict = passing.some((vote) => vote.verdict === "PASS+NOTES" || vote.findings.length > 0) ? "PASS+NOTES" : "PASS";
69
+ else if (votes.length - failing < need) verdict = "FAIL";
70
+ else verdict = "INCONCLUSIVE";
71
+ return { verdict, findings, method };
72
+ }
73
+
74
+ /**
75
+ * Have one seat judge a subject. A judgement that does not pass throws `GateFailed`, unless
76
+ * `onFail: "return"`.
77
+ */
78
+ export async function gate(key: string, opts: { subject: string; by: Seat; onFail?: "throw" | "return" }): Promise<Judged> {
79
+ checkKey(key, "the key of a gate");
80
+ const judged = await script().scope(key, undefined, async () => {
81
+ try {
82
+ return await judgeBy(opts.by, opts.subject, "check", undefined);
83
+ } catch (error) {
84
+ if (error instanceof Error && isFatal(error)) throw error;
85
+ return { verdict: "INCONCLUSIVE" as const, findings: [], method: `check by ${harnessOf(opts.by)}: no answer (${error instanceof Error ? error.message : String(error)})` };
86
+ }
87
+ });
88
+ if (!passes(judged) && (opts.onFail ?? "throw") === "throw") throw new GateFailed(opts.subject, judged);
89
+ return judged;
90
+ }
91
+
92
+ /**
93
+ * Have seats judge a subject, each through each lens, and count the votes as `require` says (every
94
+ * vote by default). `stance: "refute"` asks each judge to break the claim. A seat that shares the
95
+ * harness of `notAuthor` does not judge: with none left, the verdict is `INCONCLUSIVE`.
96
+ */
97
+ export async function verify(
98
+ key: string,
99
+ opts: { subject: string; by: readonly Seat[]; lenses?: readonly string[]; stance?: "check" | "refute"; require?: Require; notAuthor?: Seat },
100
+ ): Promise<Judged & { votes: Judged[] }> {
101
+ checkKey(key, "the key of a verification");
102
+ const stance = opts.stance ?? "check";
103
+ const require = opts.require ?? "all";
104
+ const seats = opts.notAuthor === undefined ? [...opts.by] : opts.by.filter((seat) => harnessOf(seat) !== harnessOf(opts.notAuthor as Seat));
105
+ const keys = seatKeys(seats, "the key of a seat");
106
+ const lenses = opts.lenses === undefined || opts.lenses.length === 0 ? [undefined] : [...opts.lenses];
107
+ const legs = seats.flatMap((seat, at) => lenses.map((lens, index) => ({ seat, lens, key: lens === undefined ? (keys[at] as string) : `${keys[at] as string}-l${String(index + 1)}` })));
108
+ const outcomes = await map(key, legs, { key: (leg) => leg.key }, (leg) => judgeBy(leg.seat, opts.subject, stance, leg.lens));
109
+ const votes = outcomes.map((outcome, index): Judged =>
110
+ outcome.ok ? outcome.value : { verdict: "INCONCLUSIVE", findings: [], method: `${stance} by ${harnessOf((legs[index] as { seat: Seat }).seat)}: no answer (${outcome.error.message})` },
111
+ );
112
+ const rule = typeof require === "string" ? require : `at least ${String(require.atLeast)}`;
113
+ return { ...tally(votes, require, `verify (${stance}, ${rule}) by ${String(votes.length)} vote${votes.length === 1 ? "" : "s"}`), votes };
114
+ }
115
+
116
+ /** Where a panel's winner stands: its mean score against the thresholds, or `INCONCLUSIVE` with no winner. */
117
+ export type Band = "PASS" | "WARNING" | "REVISE" | "INCONCLUSIVE";
118
+
119
+ /** Who judged in a panel: the seat's key, its harness, model and vendor. */
120
+ export type PanelJudge = { seat: string; harness: string; model?: string; vendor: string };
121
+
122
+ /** The labels a blind panel shows: A, B, ..., Z, AA, AB, ... */
123
+ export function blindLabel(index: number): string {
124
+ let label = "";
125
+ for (let n = index + 1; n > 0; n = Math.floor((n - 1) / 26)) label = String.fromCharCode(65 + ((n - 1) % 26)) + label;
126
+ return label;
127
+ }
128
+
129
+ /**
130
+ * The decision of a panel from the scores each judge gave. A sheet that does not score every
131
+ * candidate is no answer: it counts for no score and no vote. A judge votes for its highest score
132
+ * (a tie is no vote). `majority` needs more than half of the votes cast, `unanimous` a vote of
133
+ * every judge that answered; with no sheet that answered, or no vote, the panel decides nothing.
134
+ */
135
+ export function decidePanel(
136
+ candidates: readonly string[],
137
+ sheets: readonly Record<string, number>[],
138
+ rule: "majority" | "unanimous",
139
+ thresholds: { pass: number; warn: number },
140
+ ): { winner: string | null; scores: Record<string, number[]>; split: boolean; band: Band } {
141
+ const scores: Record<string, number[]> = Object.fromEntries(candidates.map((candidate) => [candidate, [] as number[]]));
142
+ const answered = sheets.filter((sheet) => candidates.every((candidate) => typeof sheet[candidate] === "number"));
143
+ const votes = new Map<string, number>();
144
+ let cast = 0;
145
+ for (const sheet of answered) {
146
+ for (const candidate of candidates) (scores[candidate] as number[]).push(sheet[candidate] as number);
147
+ const top = Math.max(...candidates.map((candidate) => sheet[candidate] as number));
148
+ const leaders = candidates.filter((candidate) => sheet[candidate] === top);
149
+ if (leaders.length === 1) {
150
+ votes.set(leaders[0] as string, (votes.get(leaders[0] as string) ?? 0) + 1);
151
+ cast += 1;
152
+ }
153
+ }
154
+ if (answered.length === 0) return { winner: null, scores, split: false, band: "INCONCLUSIVE" };
155
+ const need = rule === "unanimous" ? answered.length : Math.floor(cast / 2) + 1;
156
+ const winner = [...votes].find(([, count]) => count >= need)?.[0] ?? null;
157
+ if (winner === null) return { winner, scores, split: true, band: "INCONCLUSIVE" };
158
+ const given = scores[winner] as number[];
159
+ const mean = given.reduce((sum, score) => sum + score, 0) / given.length;
160
+ const band: Band = mean >= thresholds.pass ? "PASS" : mean >= thresholds.warn ? "WARNING" : "REVISE";
161
+ return { winner, scores, split: false, band };
162
+ }
163
+
164
+ /**
165
+ * Judges score every candidate from 0 to 100 against a rubric; the rule picks the winner and its
166
+ * mean score the band (85 and above PASS, 75 and above WARNING, else REVISE by default). With
167
+ * `blind` a judge sees labels, not the candidates' names. A judge that leaves a candidate unscored
168
+ * has not answered: its sheet counts for nothing. A judge of `authorVendor` does not judge,
169
+ * and with `distinctVendors` only the first judge of each vendor does: when none is left, the panel
170
+ * is `INCONCLUSIVE`.
171
+ */
172
+ export async function panel<C>(
173
+ key: string,
174
+ opts: {
175
+ candidates: Record<string, C>;
176
+ judges: readonly Seat[];
177
+ rubric: readonly string[];
178
+ rule?: "majority" | "unanimous";
179
+ thresholds?: { pass: number; warn: number };
180
+ distinctVendors?: boolean;
181
+ blind?: boolean;
182
+ authorVendor?: string;
183
+ },
184
+ ): Promise<{ winner: string | null; scores: Record<string, number[]>; split: boolean; band: Band; judges: PanelJudge[] }> {
185
+ checkKey(key, "the key of a panel");
186
+ const names = Object.keys(opts.candidates);
187
+ if (names.length === 0) throw new TypeError(`panel "${key}": give at least one candidate`);
188
+ const seen = new Set<string>();
189
+ const seats = opts.judges.filter((seat) => {
190
+ const vendor = vendorOf(seat);
191
+ if (opts.authorVendor !== undefined && vendor === opts.authorVendor) return false;
192
+ if (opts.distinctVendors === true) {
193
+ if (seen.has(vendor)) return false;
194
+ seen.add(vendor);
195
+ }
196
+ return true;
197
+ });
198
+ const keys = seatKeys(seats, "the key of a judge");
199
+ const judges = seats.map((seat, index): PanelJudge => ({
200
+ seat: keys[index] as string,
201
+ harness: harnessOf(seat),
202
+ vendor: vendorOf(seat),
203
+ ...(typeof seat !== "string" && seat.model !== undefined ? { model: seat.model } : {}),
204
+ }));
205
+ const thresholds = opts.thresholds ?? { pass: 85, warn: 75 };
206
+ if (seats.length === 0) return { ...decidePanel(names, [], opts.rule ?? "majority", thresholds), judges };
207
+
208
+ const shown = names.map((name, index) => (opts.blind === true ? blindLabel(index) : name));
209
+ const { z } = script();
210
+ const sheet = z.object({ scores: z.record(z.string(), z.number().min(0).max(100)) });
211
+ const prompt = [
212
+ "Score each candidate below from 0 to 100 against the rubric. Answer with a score for every candidate, by its name as shown.",
213
+ "",
214
+ "Rubric:",
215
+ ...opts.rubric.map((line) => `- ${line}`),
216
+ "",
217
+ ...names.flatMap((name, index) => {
218
+ const value = opts.candidates[name];
219
+ return [`## ${shown[index] as string}`, typeof value === "string" ? value : JSON.stringify(value, null, 2), ""];
220
+ }),
221
+ ].join("\n");
222
+ const outcomes = await map(key, seats.map((seat, index) => ({ seat, key: keys[index] as string })), { key: (one) => one.key }, (one) => askSeat(one.seat, prompt, sheet));
223
+ const sheets = outcomes.flatMap((outcome) =>
224
+ outcome.ok ? [Object.fromEntries(names.map((name, index) => [name, outcome.value.scores[shown[index] as string]]).filter(([, score]) => typeof score === "number"))] : [],
225
+ ) as Record<string, number>[];
226
+ return { ...decidePanel(names, sheets, opts.rule ?? "majority", thresholds), judges };
227
+ }