@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.
@@ -0,0 +1,331 @@
1
+ // The group helpers in a real script: a map keeps the order of its items and turns a failure into
2
+ // a value but never a refusal of the grant; a swarm reports its gaps; a stream gives its first
3
+ // passing branch; consensus agrees on what the seats answered; a graph is checked before it runs
4
+ // and runs a node once what it needs is done.
5
+
6
+ import { afterEach, expect, test } from "bun:test";
7
+
8
+ import { graphProblems, gridCells, seatKeys } from "../src/index.ts";
9
+ import { flowHost, resultOf } from "./support.ts";
10
+ import type { FlowHost } from "./support.ts";
11
+
12
+ const hosts: FlowHost[] = [];
13
+ afterEach(async () => {
14
+ for (const one of hosts.splice(0)) await one.close();
15
+ }, 30_000);
16
+
17
+ async function host(agents: Parameters<typeof flowHost>[0] = {}): Promise<FlowHost> {
18
+ const made = await flowHost(agents);
19
+ hosts.push(made);
20
+ return made;
21
+ }
22
+
23
+ test("map gives the outcomes in the order of the items, whichever ended first, and a failure as a value", async () => {
24
+ const flow = await host();
25
+ const ended = await flow.run(`
26
+ import { map } from "@niwa-labs/flow";
27
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
28
+ const out = await map("items", [30, 1, 10], { key: (n) => "n" + String(n) }, async (n) => {
29
+ await sleep(n);
30
+ if (n === 10) throw new Error("ten is not wanted");
31
+ return n * 2;
32
+ });
33
+ return out;
34
+ });`);
35
+ expect(resultOf(ended)).toEqual([
36
+ { ok: true, value: 60 },
37
+ { ok: true, value: 2 },
38
+ { ok: false, error: { name: "Error", message: "ten is not wanted" } },
39
+ ]);
40
+ }, 30_000);
41
+
42
+ test("map throws a refusal of the grant instead of keeping it as a value", async () => {
43
+ const flow = await host();
44
+ const ended = await flow.run(`
45
+ import { map } from "@niwa-labs/flow";
46
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
47
+ try {
48
+ await map("items", ["a", "b"], { key: (k) => k }, async (k) => {
49
+ if (k === "b") throw Object.assign(new Error("the grant does not hold it"), { name: "Denied" });
50
+ return k;
51
+ });
52
+ return "kept";
53
+ } catch (error) {
54
+ return (error as Error).name;
55
+ }
56
+ });`);
57
+ expect(resultOf(ended)).toBe("Denied");
58
+ }, 30_000);
59
+
60
+ test("a key that cannot name a branch, or one given twice, fails the helper before it runs anything", async () => {
61
+ const flow = await host({ worker: () => ({ answer: "x" }) });
62
+ const ended = await flow.run(`
63
+ import { map } from "@niwa-labs/flow";
64
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
65
+ const errors: string[] = [];
66
+ for (const keys of [["a", "a"], ["a.b"], [""]]) {
67
+ try {
68
+ await map("m" + String(errors.length), keys, { key: (k) => k }, async () => ask({ harness: "worker" }, "work"));
69
+ } catch (error) {
70
+ errors.push((error as Error).message);
71
+ }
72
+ }
73
+ return errors;
74
+ });`);
75
+ const errors = resultOf(ended) as string[];
76
+ expect(errors).toHaveLength(3);
77
+ expect(errors[0]).toContain("given twice");
78
+ expect(errors[1]).toContain('may not hold "."');
79
+ expect(flow.calls.worker).toHaveLength(0);
80
+ }, 30_000);
81
+
82
+ test("a swarm keeps the valid results, runs a refused worker once more and reports the gaps", async () => {
83
+ const flow = await host();
84
+ const ended = await flow.run(`
85
+ import { swarm } from "@niwa-labs/flow";
86
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
87
+ const tries: Record<string, number> = {};
88
+ const out = await swarm("crew", {
89
+ briefs: { good: 1, flaky: 2, bad: 3 },
90
+ respawn: 1,
91
+ worker: async (brief, id) => {
92
+ tries[id] = (tries[id] ?? 0) + 1;
93
+ if (id === "flaky" && tries[id] === 1) throw new Error("not this time");
94
+ return id === "bad" ? -brief : brief * 10;
95
+ },
96
+ valid: (result) => result > 0,
97
+ });
98
+ return { ...out, tries };
99
+ });`);
100
+ expect(resultOf(ended)).toEqual({ results: { good: 10, flaky: 20 }, gaps: ["bad"], dropped: ["bad"], tries: { good: 1, flaky: 2, bad: 2 } });
101
+ }, 30_000);
102
+
103
+ test("a swarm keeps the result of a brief named like a property every object has", async () => {
104
+ const flow = await host();
105
+ const ended = await flow.run(`
106
+ import { swarm } from "@niwa-labs/flow";
107
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
108
+ const out = await swarm("crew", { briefs: { ["__proto__"]: 1, plain: 2 }, worker: async (brief) => brief * 10 });
109
+ return { kept: Object.keys(out.results).sort(), gaps: out.gaps };
110
+ });`);
111
+ expect(resultOf(ended)).toEqual({ kept: ["__proto__", "plain"], gaps: [] });
112
+ }, 30_000);
113
+
114
+ test("firstPassing takes the first passing outcome of a stream and leaves the rest to be read", async () => {
115
+ const flow = await host();
116
+ const ended = await flow.run(`
117
+ import { firstPassing, stream } from "@niwa-labs/flow";
118
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
119
+ await using probes = stream("probe", {
120
+ fast: async () => { await sleep(1); return 1; },
121
+ good: async () => { await sleep(40); return 5; },
122
+ late: async () => { await sleep(150); return 7; },
123
+ });
124
+ const first = await firstPassing(probes, (n) => n > 3);
125
+ const rest = await probes.rest();
126
+ return { first, late: rest.late };
127
+ });`);
128
+ expect(resultOf(ended)).toEqual({ first: { key: "good", value: 5 }, late: { ok: true, value: 7 } });
129
+ }, 30_000);
130
+
131
+ test("consensus asks every seat and agrees on the answers that came back", async () => {
132
+ const flow = await host({ a: () => ({ n: 4 }), b: () => ({ n: 4 }), c: () => ({ n: 9 }) });
133
+ const ended = await flow.run(`
134
+ import { consensus, askSeat } from "@niwa-labs/flow";
135
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
136
+ const out = await consensus("count", {
137
+ seats: ["a", "b", "c"],
138
+ run: (seat) => askSeat(seat, "How many?", z.object({ n: z.number() })),
139
+ agree: (all) => {
140
+ const counts = new Map<number, number>();
141
+ for (const one of all) counts.set(one.n, (counts.get(one.n) ?? 0) + 1);
142
+ const top = [...counts].find(([, c]) => c * 2 > all.length);
143
+ return top === undefined ? null : { n: top[0] };
144
+ },
145
+ });
146
+ return out.value;
147
+ });`);
148
+ expect(resultOf(ended)).toEqual({ n: 4 });
149
+ expect([flow.calls.a, flow.calls.b, flow.calls.c].map((calls) => calls?.length)).toEqual([1, 1, 1]);
150
+ }, 30_000);
151
+
152
+ test("a graph runs a node once what it needs is done, skips below a failure and gives each node what it needs", async () => {
153
+ const flow = await host();
154
+ const ended = await flow.run(`
155
+ import { graph } from "@niwa-labs/flow";
156
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
157
+ const order: string[] = [];
158
+ const out = await graph("build", [
159
+ { id: "lib", needs: [] },
160
+ { id: "app", needs: ["lib"] },
161
+ { id: "docs", needs: [] },
162
+ { id: "broken", needs: ["docs"] },
163
+ { id: "site", needs: ["broken", "app"] },
164
+ ], {
165
+ run: async (node, done) => {
166
+ order.push(node.id);
167
+ if (node.id === "broken") throw new Error("it broke");
168
+ return node.id + "(" + Object.keys(done).sort().join(",") + ")";
169
+ },
170
+ });
171
+ return { order, ...out };
172
+ });`);
173
+ const out = resultOf(ended) as { order: string[]; results: Record<string, { ok: boolean; value?: string }>; skipped: string[] };
174
+ expect(out.results.app).toEqual({ ok: true, value: "app(docs,lib)" });
175
+ expect(out.results.broken?.ok).toBe(false);
176
+ expect(out.skipped).toEqual(["site"]);
177
+ expect(out.order.slice(0, 2)).toEqual(["docs", "lib"]);
178
+ }, 30_000);
179
+
180
+ test("a node named like a property every object has waits for that node, and its result is kept", async () => {
181
+ const flow = await host();
182
+ const ended = await flow.run(`
183
+ import { graph } from "@niwa-labs/flow";
184
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
185
+ const out = await graph("names", [
186
+ { id: "constructor", needs: [] },
187
+ { id: "after", needs: ["constructor", "__proto__"] },
188
+ { id: "__proto__", needs: [] },
189
+ ], {
190
+ run: async (node, done) => {
191
+ if (node.id !== "after") { await sleep(20); return node.id + "-done"; }
192
+ return Object.keys(done).sort();
193
+ },
194
+ });
195
+ return { keys: Object.keys(out.results).sort(), after: out.results.after };
196
+ });`);
197
+ expect(resultOf(ended)).toEqual({ keys: ["__proto__", "after", "constructor"], after: { ok: true, value: ["__proto__", "constructor"] } });
198
+ }, 30_000);
199
+
200
+ test("a graph with a missing node, an id given twice or a cycle is refused before it runs", () => {
201
+ expect(graphProblems([{ id: "a", needs: ["ghost"] }])).toEqual(['the node "a" needs "ghost", which is not in the graph']);
202
+ expect(graphProblems([{ id: "a", needs: [] }, { id: "a", needs: [] }])).toEqual(['the node "a" is given twice']);
203
+ expect(graphProblems([{ id: "a", needs: ["b"] }, { id: "b", needs: ["c"] }, { id: "c", needs: ["a"] }])).toEqual(["the nodes form a cycle: a -> b -> c -> a"]);
204
+ expect(graphProblems([{ id: "a", needs: [] }, { id: "b", needs: ["a"] }])).toEqual([]);
205
+ });
206
+
207
+ test("the cells of a grid are every combination, in the order of its keys and values", () => {
208
+ expect(gridCells({ size: [1, 2], mode: ["x", "y"] })).toEqual([
209
+ { size: 1, mode: "x" },
210
+ { size: 1, mode: "y" },
211
+ { size: 2, mode: "x" },
212
+ { size: 2, mode: "y" },
213
+ ]);
214
+ });
215
+ test("seat keys number a seat met again with a name no other seat has", () => {
216
+ expect(seatKeys(["judge", "judge", "judge-2"], "a seat")).toEqual(["judge", "judge-3", "judge-2"]);
217
+ expect(seatKeys(["judge-2", "judge", "judge"], "a seat")).toEqual(["judge-2", "judge", "judge-3"]);
218
+ expect(seatKeys(["a", "a", "a"], "a seat")).toEqual(["a", "a-2", "a-3"]);
219
+ });
220
+
221
+
222
+ test("map throws a refusal of the grant as soon as it is committed, not when the branches before it ended", async () => {
223
+ const flow = await host();
224
+ const ended = await flow.run(`
225
+ import { map } from "@niwa-labs/flow";
226
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
227
+ try {
228
+ await map("items", ["slow", "refused"], { key: (k) => k }, async (k) => {
229
+ if (k === "slow") { await sleep("1h"); return k; }
230
+ throw Object.assign(new Error("the grant does not hold it"), { name: "Denied" });
231
+ });
232
+ return "kept";
233
+ } catch (error) {
234
+ return (error as Error).name;
235
+ }
236
+ });`);
237
+ expect(resultOf(ended)).toBe("Denied");
238
+ }, 30_000);
239
+
240
+ test("a question the owner left unanswered leaves a map and a swarm, and a worker that met it is not run again", async () => {
241
+ const flow = await host();
242
+ const ended = await flow.run(`
243
+ import { map, swarm } from "@niwa-labs/flow";
244
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
245
+ const mapped = await map("asks", ["a"], { key: (k) => k }, async () => ask.confirm("Go on?", { timeout: "50ms" })).then(() => "kept", (error) => (error as Error).name);
246
+ let tries = 0;
247
+ const swarmed = await swarm("crew", {
248
+ briefs: { one: 1 },
249
+ respawn: 1,
250
+ worker: async () => { tries += 1; return ask.confirm("Go on?", { timeout: "50ms" }); },
251
+ }).then(() => "kept", (error) => (error as Error).name);
252
+ return { mapped, swarmed, tries };
253
+ });`);
254
+ expect(resultOf(ended)).toEqual({ mapped: "AskExpired", swarmed: "AskExpired", tries: 1 });
255
+ }, 30_000);
256
+
257
+ test("a swarm worker that opens a named scope can run again after a failed attempt", async () => {
258
+ const flow = await host();
259
+ const ended = await flow.run(`
260
+ import { swarm } from "@niwa-labs/flow";
261
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
262
+ let tries = 0;
263
+ return swarm("crew", {
264
+ briefs: { one: 1 },
265
+ respawn: 1,
266
+ worker: async (brief) => scope("work", undefined, async () => {
267
+ tries += 1;
268
+ if (tries === 1) throw new Error("not this time");
269
+ return brief * 7;
270
+ }),
271
+ });
272
+ });`);
273
+ expect(resultOf(ended)).toEqual({ results: { one: 7 }, gaps: [], dropped: [] });
274
+ }, 30_000);
275
+
276
+ test("a stream that cannot be opened gives every read the error of its opening", async () => {
277
+ const flow = await host();
278
+ const ended = await flow.run(`
279
+ import { stream } from "@niwa-labs/flow";
280
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
281
+ const first = stream("dup", { x: async () => 1 });
282
+ const second = stream("dup", { x: async () => 2 });
283
+ const errors: string[] = [];
284
+ for (const read of [() => second.next(), () => second.rest(), () => second.pending()]) {
285
+ await read().catch((error) => errors.push((error as Error).message));
286
+ }
287
+ return { errors, first: await first.next() };
288
+ });`);
289
+ const out = resultOf(ended) as { errors: string[]; first: unknown };
290
+ expect(out.errors).toHaveLength(3);
291
+ for (const message of out.errors) expect(message).toContain("opened twice");
292
+ expect(out.first).toEqual({ key: "x", result: { ok: true, value: 1 } });
293
+ }, 30_000);
294
+
295
+ test("every way to read a stream throws a refusal of the grant", async () => {
296
+ const flow = await host();
297
+ const ended = await flow.run(`
298
+ import { stream } from "@niwa-labs/flow";
299
+ const refused = async () => { throw Object.assign(new Error("the grant does not hold it"), { name: "Denied" }); };
300
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
301
+ const name = (read: () => Promise<unknown>) => read().then(() => "kept", (error) => (error as Error).name);
302
+ const next = await name(async () => stream("next", { refused }).next());
303
+ const rest = await name(async () => stream("rest", { refused }).rest());
304
+ const ready = await name(async () => {
305
+ const s = stream("ready", { refused });
306
+ for (let tries = 0; tries < 100; tries += 1) {
307
+ const got = await s.ready();
308
+ if (got.length > 0) return got;
309
+ await sleep(20);
310
+ }
311
+ return "nothing was ready";
312
+ });
313
+ const each = await name(async () => { for await (const _ of stream("each", { refused })) { /* read */ } });
314
+ return { next, rest, ready, each };
315
+ });`);
316
+ expect(resultOf(ended)).toEqual({ next: "Denied", rest: "Denied", ready: "Denied", each: "Denied" });
317
+ }, 30_000);
318
+
319
+ test("a branch keyed __proto__ keeps its outcome in parallel, in the rest of a stream and when ranked", async () => {
320
+ const flow = await host();
321
+ const ended = await flow.run(`
322
+ import { parallel, rankAll, stream } from "@niwa-labs/flow";
323
+ const own = (table: object) => Object.keys(table);
324
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
325
+ const done = await parallel<string, any>({ ["__proto__"]: async () => ({ n: 1 }), plain: async () => 2 });
326
+ const rest = await stream("rest", { ["__proto__"]: async () => { throw new Error("no"); }, plain: async () => 2 }).rest();
327
+ const ranked = await rankAll(stream("rank", { ["__proto__"]: async () => 5, plain: async () => 2 }), async () => "__proto__");
328
+ return { done: own(done), n: Object.getOwnPropertyDescriptor(done, "__proto__")?.value, rest: own(rest), failed: Object.getOwnPropertyDescriptor(rest, "__proto__")?.value?.ok, ranked: ranked.value };
329
+ });`);
330
+ expect(resultOf(ended)).toEqual({ done: ["__proto__", "plain"], n: { n: 1 }, rest: ["__proto__", "plain"], failed: false, ranked: 5 });
331
+ }, 30_000);
@@ -0,0 +1,215 @@
1
+ // Loops and judging in a real script: revise writes again with the last judgement and stops on a
2
+ // pass, never on INCONCLUSIVE; verify counts votes as asked and a judge that does not answer is no
3
+ // pass; a gate throws on a fail; a panel with no judge independent of the author decides nothing.
4
+
5
+ import { afterEach, expect, test } from "bun:test";
6
+
7
+ import { blindLabel, decidePanel, tally } from "../src/index.ts";
8
+ import type { Judged } from "../src/index.ts";
9
+ import { flowHost, resultOf } from "./support.ts";
10
+ import type { FlowHost, Reply } from "./support.ts";
11
+
12
+ const hosts: FlowHost[] = [];
13
+ afterEach(async () => {
14
+ for (const one of hosts.splice(0)) await one.close();
15
+ }, 30_000);
16
+
17
+ async function host(agents: Record<string, Reply> = {}): Promise<FlowHost> {
18
+ const made = await flowHost(agents);
19
+ hosts.push(made);
20
+ return made;
21
+ }
22
+
23
+ const vote = (verdict: Judged["verdict"], notes = 0): Judged => ({
24
+ verdict,
25
+ findings: Array.from({ length: notes }, (_, i) => ({ title: `n${String(i)}`, evidence: "e", severity: "note" as const })),
26
+ method: "m",
27
+ });
28
+
29
+ test("tally passes on enough passing votes, fails when a pass cannot be reached, and is inconclusive otherwise", () => {
30
+ expect(tally([vote("PASS"), vote("PASS")], "all", "m").verdict).toBe("PASS");
31
+ expect(tally([vote("PASS"), vote("PASS", 1)], "all", "m").verdict).toBe("PASS+NOTES");
32
+ expect(tally([vote("PASS"), vote("INCONCLUSIVE")], "all", "m").verdict).toBe("INCONCLUSIVE");
33
+ expect(tally([vote("PASS"), vote("FAIL")], "all", "m").verdict).toBe("FAIL");
34
+ expect(tally([vote("PASS"), vote("PASS"), vote("FAIL")], "majority", "m").verdict).toBe("PASS");
35
+ expect(tally([vote("INCONCLUSIVE"), vote("INCONCLUSIVE"), vote("PASS")], "majority", "m").verdict).toBe("INCONCLUSIVE");
36
+ expect(tally([vote("FAIL"), vote("FAIL"), vote("PASS")], { atLeast: 2 }, "m").verdict).toBe("FAIL");
37
+ expect(tally([], "all", "m").verdict).toBe("INCONCLUSIVE");
38
+ });
39
+
40
+ test("a panel votes for each judge's top score, bands the winner's mean and is split when no rule holds", () => {
41
+ const two = ["x", "y"];
42
+ expect(decidePanel(two, [{ x: 90, y: 10 }, { x: 88, y: 20 }], "majority", { pass: 85, warn: 75 })).toEqual({
43
+ winner: "x",
44
+ scores: { x: [90, 88], y: [10, 20] },
45
+ split: false,
46
+ band: "PASS",
47
+ });
48
+ expect(decidePanel(two, [{ x: 80, y: 10 }, { x: 78, y: 20 }], "unanimous", { pass: 85, warn: 75 }).band).toBe("WARNING");
49
+ expect(decidePanel(two, [{ x: 90, y: 10 }, { x: 10, y: 90 }], "majority", { pass: 85, warn: 75 })).toMatchObject({ winner: null, split: true, band: "INCONCLUSIVE" });
50
+ expect(decidePanel(two, [], "majority", { pass: 85, warn: 75 })).toMatchObject({ winner: null, band: "INCONCLUSIVE" });
51
+ expect([0, 25, 26, 701].map(blindLabel)).toEqual(["A", "Z", "AA", "ZZ"]);
52
+ });
53
+
54
+ test("revise writes again with the judgement it got and stops at the first pass", async () => {
55
+ const flow = await host();
56
+ const ended = await flow.run(`
57
+ import { revise } from "@niwa-labs/flow";
58
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
59
+ const seen: Array<string | null> = [];
60
+ const out = await revise("draft", {
61
+ max: 5,
62
+ write: async (feedback, round) => {
63
+ seen.push(feedback === null ? null : feedback.verdict);
64
+ return "v" + String(round);
65
+ },
66
+ judge: async (value) => ({
67
+ verdict: value === "v1" ? "FAIL" : value === "v2" ? "INCONCLUSIVE" : "PASS",
68
+ findings: [],
69
+ method: "test",
70
+ }),
71
+ });
72
+ return { seen, value: out.value, rounds: out.rounds, stopped: out.stopped, history: out.history.map((j) => j.verdict) };
73
+ });`);
74
+ expect(resultOf(ended)).toEqual({ seen: [null, "FAIL", "INCONCLUSIVE"], value: "v3", rounds: 3, stopped: "accepted", history: ["FAIL", "INCONCLUSIVE", "PASS"] });
75
+ }, 30_000);
76
+
77
+ test("revise stops at its most rounds with the last value, and a helper inside each round is keyed by its round", async () => {
78
+ const flow = await host({ critic: () => ({ verdict: "INCONCLUSIVE", findings: [{ title: "unsure", evidence: "no tests", severity: "blocks" }] }) });
79
+ const ended = await flow.run(`
80
+ import { revise, verify } from "@niwa-labs/flow";
81
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
82
+ const out = await revise("draft", {
83
+ max: 2,
84
+ write: async (_feedback, round) => "v" + String(round),
85
+ judge: (value) => verify("check", { subject: value, by: ["critic"] }),
86
+ });
87
+ return { value: out.value, rounds: out.rounds, stopped: out.stopped, verdict: out.judged.verdict };
88
+ });`);
89
+ expect(resultOf(ended)).toEqual({ value: "v2", rounds: 2, stopped: "max-rounds", verdict: "INCONCLUSIVE" });
90
+ expect(flow.calls.critic).toHaveLength(2);
91
+ expect(flow.calls.critic?.[1]?.prompt).toContain("v2");
92
+ }, 30_000);
93
+
94
+ test("verify asks every seat through every lens and a failing vote fails what needs all", async () => {
95
+ const flow = await host({
96
+ lenient: () => ({ verdict: "PASS", findings: [] }),
97
+ strict: (call) => (call.prompt.includes("security") ? { verdict: "FAIL", findings: [{ title: "secret in log", evidence: "line 3", severity: "blocks" }] } : { verdict: "PASS", findings: [] }),
98
+ });
99
+ const ended = await flow.run(`
100
+ import { verify } from "@niwa-labs/flow";
101
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
102
+ const all = await verify("all", { subject: "the patch", by: ["lenient", "strict"], lenses: ["security", "style"] });
103
+ const most = await verify("most", { subject: "the patch", by: ["lenient", "strict"], lenses: ["security", "style"], require: "majority" });
104
+ const alone = await verify("alone", { subject: "the patch", by: ["strict"], notAuthor: "strict" });
105
+ return { all: all.verdict, votes: all.votes.length, findings: all.findings.map((f) => f.title), most: most.verdict, alone: alone.verdict };
106
+ });`);
107
+ expect(resultOf(ended)).toEqual({ all: "FAIL", votes: 4, findings: ["secret in log"], most: "PASS", alone: "INCONCLUSIVE" });
108
+ expect(flow.calls.strict?.[0]?.prompt).toContain("security");
109
+ }, 30_000);
110
+
111
+ test("a gate that does not pass throws, or answers the judgement when asked to return", async () => {
112
+ const flow = await host({ judge: () => ({ verdict: "FAIL", findings: [{ title: "wrong", evidence: "x", severity: "blocks" }] }) });
113
+ const ended = await flow.run(`
114
+ import { gate } from "@niwa-labs/flow";
115
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
116
+ const returned = await gate("soft", { subject: "s", by: "judge", onFail: "return" });
117
+ try {
118
+ await gate("hard", { subject: "s", by: "judge" });
119
+ return "opened";
120
+ } catch (error) {
121
+ return { name: (error as Error).name, returned: returned.verdict };
122
+ }
123
+ });`);
124
+ expect(resultOf(ended)).toEqual({ name: "GateFailed", returned: "FAIL" });
125
+ }, 30_000);
126
+
127
+ test("a panel scores blind candidates, and with no judge independent of the author decides nothing", async () => {
128
+ const flow = await host({
129
+ one: (call) => ({ scores: call.prompt.includes("## A\nshort") ? { A: 60, B: 92 } : { A: 92, B: 60 } }),
130
+ two: () => ({ scores: { A: 50, B: 90 } }),
131
+ });
132
+ const ended = await flow.run(`
133
+ import { panel } from "@niwa-labs/flow";
134
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
135
+ const candidates = { short: "short", long: "a longer answer" };
136
+ const judged = await panel("pick", { candidates, judges: [{ harness: "one", vendor: "v1" }, { harness: "two", vendor: "v2" }], rubric: ["clear"], blind: true });
137
+ const own = await panel("own", { candidates, judges: [{ harness: "one", vendor: "v1" }], rubric: ["clear"], authorVendor: "v1" });
138
+ return { winner: judged.winner, band: judged.band, own: own.band, ownWinner: own.winner };
139
+ });`);
140
+ expect(resultOf(ended)).toEqual({ winner: "long", band: "PASS", own: "INCONCLUSIVE", ownWinner: null });
141
+ expect(flow.calls.one?.[0]?.prompt).not.toContain("## short");
142
+ expect(flow.calls.one).toHaveLength(1);
143
+ }, 30_000);
144
+
145
+ test("a loop steps until done or its most rounds, and saturation stops when a round finds nothing new", async () => {
146
+ const flow = await host();
147
+ const ended = await flow.run(`
148
+ import { loop, saturate } from "@niwa-labs/flow";
149
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
150
+ const counted = await loop("count", { init: 0, step: async (n) => n + 2, done: (n) => n >= 5, max: 10 });
151
+ const capped = await loop("cap", { init: 0, step: async (n) => n + 1, done: (n) => n >= 5, max: 2 });
152
+ const found = await saturate("find", { step: async (_seen, round) => (round < 3 ? [round, round] : [1]), same: (a, b) => a === b, max: 9 });
153
+ return { counted, capped, found };
154
+ });`);
155
+ expect(resultOf(ended)).toEqual({
156
+ counted: { state: 6, rounds: 3, hitMax: false },
157
+ capped: { state: 2, rounds: 2, hitMax: true },
158
+ found: { items: [1, 2], rounds: 3, saturated: true },
159
+ });
160
+ }, 30_000);
161
+
162
+ test("a script's output can be the Attempt of a revision judged by verify, votes and all", async () => {
163
+ const flow = await host({ checker: () => ({ verdict: "PASS", findings: [] }) });
164
+ const ended = await flow.run(`
165
+ import { Attempt, revise, verify } from "@niwa-labs/flow";
166
+ export default workflow({ output: Attempt(z.object({ n: z.number() })) }, async () =>
167
+ revise("count", {
168
+ write: async (_feedback, round) => ({ n: round }),
169
+ judge: ({ n }) => verify("check", { subject: String(n), by: ["checker"] }),
170
+ }));`);
171
+ expect(resultOf(ended)).toMatchObject({ value: { n: 1 }, rounds: 1, stopped: "accepted", judged: { verdict: "PASS", votes: [{ verdict: "PASS" }] } });
172
+ }, 30_000);
173
+
174
+ test("a panel counts only the sheets that score every candidate", () => {
175
+ const two = ["x", "y"];
176
+ const rules = { pass: 85, warn: 75 };
177
+ expect(decidePanel(two, [{ x: 99 }], "majority", rules)).toMatchObject({ winner: null, band: "INCONCLUSIVE", scores: { x: [], y: [] } });
178
+ expect(decidePanel(two, [{ x: 99 }, { x: 90, y: 10 }], "unanimous", rules)).toMatchObject({ winner: "x", scores: { x: [90], y: [10] } });
179
+ });
180
+
181
+ test("a majority of a panel is of the judges that voted, a tie being no vote", () => {
182
+ const two = ["x", "y"];
183
+ const rules = { pass: 85, warn: 75 };
184
+ const tied = { x: 50, y: 50 };
185
+ expect(decidePanel(two, [{ x: 90, y: 10 }, tied, tied], "majority", rules)).toMatchObject({ winner: "x", split: false });
186
+ expect(decidePanel(two, [{ x: 90, y: 10 }, tied], "unanimous", rules)).toMatchObject({ winner: null, split: true });
187
+ expect(decidePanel(two, [tied, tied], "majority", rules)).toMatchObject({ winner: null, split: true, band: "INCONCLUSIVE" });
188
+ });
189
+
190
+ test("a panel whose judge scored only some candidates decides nothing", async () => {
191
+ const flow = await host({ partial: () => ({ scores: { A: 99 } }) });
192
+ const ended = await flow.run(`
193
+ import { panel } from "@niwa-labs/flow";
194
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
195
+ const out = await panel("pick", { candidates: { one: "first", two: "second" }, judges: [{ harness: "partial", vendor: "v" }], rubric: ["clear"], blind: true });
196
+ return { winner: out.winner, band: out.band, scores: out.scores };
197
+ });`);
198
+ expect(resultOf(ended)).toEqual({ winner: null, band: "INCONCLUSIVE", scores: { one: [], two: [] } });
199
+ }, 30_000);
200
+
201
+ test("a grid gives a cell that failed no score, and refuses a score that is not a finite number", async () => {
202
+ const flow = await host();
203
+ const ended = await flow.run(`
204
+ import { paramGrid } from "@niwa-labs/flow";
205
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
206
+ const grid = await paramGrid("grid", {
207
+ grid: { n: [1, 2, 3] },
208
+ run: async (cell) => { if (cell.n === 2) throw new Error("no"); return cell.n; },
209
+ score: (n) => n * 10,
210
+ });
211
+ const refused = await paramGrid("nan", { grid: { n: [1] }, run: async (cell) => cell.n, score: () => Number.NaN }).then(() => "kept", (error) => (error as Error).name);
212
+ return { scores: grid.cells.map((cell) => cell.score), best: grid.best, refused };
213
+ });`);
214
+ expect(resultOf(ended)).toEqual({ scores: [10, null, 30], best: 2, refused: "TypeError" });
215
+ }, 30_000);
@@ -0,0 +1,108 @@
1
+ // The helpers that order work, in a real script: map-reduce in batches, a pick over every outcome
2
+ // of a stream, a grid of parameters scored cell by cell, and a revision up a ladder of seats.
3
+
4
+ import { afterEach, expect, test } from "bun:test";
5
+
6
+ import { flowHost, resultOf } from "./support.ts";
7
+ import type { FlowHost } from "./support.ts";
8
+
9
+ const hosts: FlowHost[] = [];
10
+ afterEach(async () => {
11
+ for (const one of hosts.splice(0)) await one.close();
12
+ }, 30_000);
13
+
14
+ async function host(agents: Parameters<typeof flowHost>[0] = {}): Promise<FlowHost> {
15
+ const made = await flowHost(agents);
16
+ hosts.push(made);
17
+ return made;
18
+ }
19
+
20
+ test("map-reduce maps the items in batches and reduces the outcomes in the order of the batches", async () => {
21
+ const flow = await host();
22
+ const ended = await flow.run(`
23
+ import { mapReduce } from "@niwa-labs/flow";
24
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
25
+ const batches: number[][] = [];
26
+ const total = await mapReduce("sum", [1, 2, 3, 4, 5], {
27
+ batch: 2,
28
+ key: (n) => "n" + String(n),
29
+ map: async (batch) => {
30
+ batches.push(batch);
31
+ await sleep(10 * (3 - batch.length));
32
+ if (batch.includes(5)) throw new Error("five is not wanted");
33
+ return batch.reduce((sum, n) => sum + n, 0);
34
+ },
35
+ reduce: async (parts) => parts.map((part) => (part.ok ? part.value : part.error.message)),
36
+ });
37
+ return { total, batches: batches.length };
38
+ });`);
39
+ expect(resultOf(ended)).toEqual({ total: [3, 7, "five is not wanted"], batches: 3 });
40
+ }, 30_000);
41
+
42
+ test("rankAll waits for every outcome of a stream, then takes the branch the ranking picks", async () => {
43
+ const flow = await host();
44
+ const ended = await flow.run(`
45
+ import { rankAll, stream } from "@niwa-labs/flow";
46
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
47
+ await using drafts = stream("drafts", {
48
+ short: async () => "ab",
49
+ long: async () => { await sleep(20); return "abcd"; },
50
+ broken: async (): Promise<string> => { throw new Error("no draft"); },
51
+ });
52
+ const best = await rankAll(drafts, async (all) => {
53
+ const lengths = Object.entries(all).map(([key, one]) => [key, one.ok ? one.value.length : -1] as const);
54
+ return lengths.sort((a, b) => b[1] - a[1])[0]![0] as "short" | "long" | "broken";
55
+ });
56
+ await using again = stream("again", { broken: async (): Promise<string> => { throw new Error("no draft"); } });
57
+ const refused = await rankAll(again, async () => "broken" as const).then(() => "picked", (error: Error) => error.message);
58
+ await using other = stream("other", { only: async () => "x" });
59
+ const unknown = await rankAll(other, async () => "constructor" as "only").then(() => "picked", (error: Error) => error.message);
60
+ return { key: best.key, value: best.value, seen: Object.keys(best.all).sort(), refused, unknown };
61
+ });`);
62
+ expect(resultOf(ended)).toEqual({
63
+ key: "long",
64
+ value: "abcd",
65
+ seen: ["broken", "long", "short"],
66
+ refused: 'rankAll: "broken" failed (no draft), it cannot be picked',
67
+ unknown: 'rankAll: "constructor" is not a branch of the stream',
68
+ });
69
+ }, 30_000);
70
+
71
+ test("a grid runs every cell, scores the ones that ran and names the best, a failed cell scoring nothing", async () => {
72
+ const flow = await host();
73
+ const ended = await flow.run(`
74
+ import { paramGrid } from "@niwa-labs/flow";
75
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
76
+ const out = await paramGrid("tune", {
77
+ grid: { size: [1, 2, 3], scale: [10] },
78
+ run: async (cell) => {
79
+ if (cell.size === 3) throw new Error("too big");
80
+ return cell.size * cell.scale;
81
+ },
82
+ score: (result) => result,
83
+ });
84
+ return { scores: out.cells.map((cell) => (cell.result.ok ? cell.score : null)), best: out.best };
85
+ });`);
86
+ expect(resultOf(ended)).toEqual({ scores: [10, 20, null], best: 1 });
87
+ }, 30_000);
88
+
89
+ test("escalate writes with the next seat after each failed judgement, and stops at the first pass", async () => {
90
+ const flow = await host({ cheap: () => ({ answer: "a guess" }), strong: () => ({ answer: "the answer" }), top: () => ({ answer: "unused" }) });
91
+ const ended = await flow.run(`
92
+ import { escalate } from "@niwa-labs/flow";
93
+ export default workflow({ uses: ["session.start.*"], output: z.json() }, async (): Promise<any> => {
94
+ const out = await escalate("solve", {
95
+ seats: ["cheap", "strong", "top"],
96
+ write: async (seat, feedback) => (await ask({ harness: seat as "cheap" | "strong" | "top" }, "Solve it." + (feedback === null ? "" : " Last time: " + feedback.findings[0]!.title))).answer,
97
+ judge: async (value) =>
98
+ value === "the answer"
99
+ ? { verdict: "PASS", findings: [], method: "exact" }
100
+ : { verdict: "FAIL", findings: [{ title: "a guess is not an answer", evidence: value, severity: "blocks" }], method: "exact" },
101
+ });
102
+ return { value: out.value, rounds: out.rounds, stopped: out.stopped };
103
+ });`);
104
+ expect(resultOf(ended)).toEqual({ value: "the answer", rounds: 2, stopped: "accepted" });
105
+ expect(flow.calls.cheap?.map((call) => call.prompt)).toEqual(["Solve it."]);
106
+ expect(flow.calls.strong?.map((call) => call.prompt)).toEqual(["Solve it. Last time: a guess is not an answer"]);
107
+ expect(flow.calls.top).toEqual([]);
108
+ }, 30_000);