@harperfast/harper-pro 5.0.25 → 5.1.0-beta.1

package/core/agent/tools/httpFetchTool.ts

@@ -0,0 +1,112 @@
+/**
+ * `http_fetch` for the built-in agent (#626). Wraps the platform `fetch`
+ * with a size cap, an inactivity timeout, and a metadata/loopback blocklist
+ * so the agent can probe its own deployed components and pull lightweight
+ * web pages for context without becoming an SSRF vector against cloud
+ * instance-metadata endpoints or unrelated internal services.
+ */
+
+import { isIP } from 'node:net';
+import type { AgentTool, AgentToolContext } from '../types.ts';
+
+const MAX_BYTES = 2 * 1024 * 1024; // 2 MiB cap on response bodies
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Hard-blocked literal hosts. Cloud-metadata services live on these IPs and exposing them
+// to a prompt-controlled fetch is a credential-leak vector. Loopback to the local Harper
+// instance is allowed via `localhost`/`127.0.0.1` for self-testing — those are NOT blocked.
+const BLOCKED_HOSTS = new Set([
+	'169.254.169.254', // AWS / GCP / Azure IMDS
+	'fd00:ec2::254', // AWS IMDSv2 IPv6
+	'metadata.google.internal',
+	'metadata.goog',
+]);
+
+export const httpFetchTool: AgentTool = {
+	def: {
+		name: 'http_fetch',
+		description:
+			"Issue an HTTP request from the Harper server. Useful for hitting the agent's own components on localhost and pulling reference pages.",
+		parameters: {
+			type: 'object',
+			properties: {
+				url: { type: 'string', description: 'Absolute URL.' },
+				method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] },
+				headers: { type: 'object', additionalProperties: { type: 'string' } },
+				body: { type: 'string', description: 'Request body as a string (JSON or form-encoded).' },
+				timeoutMs: { type: 'integer', minimum: 1, maximum: 120_000 },
+			},
+			required: ['url'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const url = String(args.url ?? '');
+		if (!/^https?:\/\//i.test(url)) throw new Error('http_fetch requires an http(s) URL');
+		let parsed: URL;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new Error(`http_fetch could not parse URL: ${url}`);
+		}
+		const host = parsed.hostname.toLowerCase();
+		if (BLOCKED_HOSTS.has(host)) {
+			throw new Error(`http_fetch blocked by metadata-host policy: ${host}`);
+		}
+		// IPv4 link-local (169.254.0.0/16) covers IMDS variants beyond the canonical 169.254.169.254.
+		if (isIP(host) === 4 && host.startsWith('169.254.')) {
+			throw new Error(`http_fetch blocked by link-local policy: ${host}`);
+		}
+		const timeoutMs = Math.min(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, 120_000);
+		const localAbort = new AbortController();
+		const timer = setTimeout(() => localAbort.abort(new Error(`http_fetch timed out after ${timeoutMs}ms`)), timeoutMs);
+		const signal = combineSignals(ctx.signal, localAbort.signal);
+		try {
+			const response = await fetch(url, {
+				method: args.method ?? 'GET',
+				headers: args.headers,
+				body: args.body,
+				signal,
+			});
+			const buffer = await readCapped(response, MAX_BYTES);
+			return {
+				status: response.status,
+				headers: Object.fromEntries(response.headers.entries()),
+				body: buffer.toString('utf8'),
+				truncated: buffer.length === MAX_BYTES,
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	},
+};
+
+async function readCapped(response: Response, cap: number): Promise<Buffer> {
+	const reader = response.body?.getReader();
+	if (!reader) return Buffer.alloc(0);
+	const chunks: Buffer[] = [];
+	let total = 0;
+	while (total < cap) {
+		const { value, done } = await reader.read();
+		if (done) break;
+		const chunk = Buffer.from(value);
+		const room = cap - total;
+		if (chunk.length > room) {
+			chunks.push(chunk.subarray(0, room));
+			total += room;
+			await reader.cancel().catch(() => {});
+			break;
+		}
+		chunks.push(chunk);
+		total += chunk.length;
+	}
+	return Buffer.concat(chunks, total);
+}
+
+function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+	const present = signals.filter((s): s is AbortSignal => Boolean(s));
+	if (present.length === 0) return undefined;
+	if (present.length === 1) return present[0];
+	// `AbortSignal.any` (Node 20+) manages listener cleanup internally; the manual
+	// `addEventListener` approach leaked listeners on `ctx.signal` for the lifetime of the agent
+	// run when a fetch completed normally.
+	return AbortSignal.any(present);
+}

package/core/agent/tools/scheduleTool.ts

@@ -0,0 +1,68 @@
+/**
+ * `schedule_followup` for the built-in agent (#626).
+ *
+ * Lives on the main thread so it survives worker-thread restarts that happen
+ * on code reload. The followup callback is injected from the entry point —
+ * this module only schedules the timer and tracks pending entries.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { AgentTool, AgentToolContext } from '../types.ts';
+
+const MAX_DELAY_MS = 24 * 60 * 60 * 1000; // 24h
+const MIN_DELAY_MS = 1_000;
+
+export interface ScheduledFollowup {
+	id: string;
+	sessionId: string;
+	prompt: string;
+	fireAt: number;
+	timer: NodeJS.Timeout;
+}
+
+export interface ScheduleToolDeps {
+	onFollowup: (sessionId: string, prompt: string) => Promise<void> | void;
+}
+
+export function buildScheduleTool(deps: ScheduleToolDeps): {
+	tool: AgentTool;
+	pending: Map<string, ScheduledFollowup>;
+} {
+	const pending = new Map<string, ScheduledFollowup>();
+	const tool: AgentTool = {
+		def: {
+			name: 'schedule_followup',
+			description: 'Re-invoke the agent on the current session after the given delay with a new prompt.',
+			parameters: {
+				type: 'object',
+				properties: {
+					delayMs: { type: 'integer', minimum: MIN_DELAY_MS, maximum: MAX_DELAY_MS },
+					prompt: { type: 'string', description: 'Prompt the agent should re-enter on with.' },
+				},
+				required: ['delayMs', 'prompt'],
+			},
+		},
+		handler: async (args: any, ctx: AgentToolContext) => {
+			const delay = Number(args.delayMs);
+			if (!Number.isFinite(delay) || delay < MIN_DELAY_MS || delay > MAX_DELAY_MS) {
+				throw new Error(`delayMs must be between ${MIN_DELAY_MS} and ${MAX_DELAY_MS}`);
+			}
+			const prompt = String(args.prompt ?? '').trim();
+			if (!prompt) throw new Error('prompt is required');
+			const id = randomUUID();
+			const fireAt = Date.now() + delay;
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				Promise.resolve()
+					.then(() => deps.onFollowup(ctx.sessionId, prompt))
+					.catch(() => {
+						/* swallow — caller logs */
+					});
+			}, delay);
+			timer.unref?.();
+			pending.set(id, { id, sessionId: ctx.sessionId, prompt, fireAt, timer });
+			return { id, fireAt };
+		},
+	};
+	return { tool, pending };
+}

package/core/agent/toolset.ts

@@ -0,0 +1,43 @@
+/**
+ * Tool composer for the built-in agent (#626).
+ *
+ * Operator-only tools (FS, schedule, fetch) are inline today. Once the
+ * unified MCP tool registry (#615) lands with the Operations (#617) and
+ * Application (#618) profiles, this is the seam where RBAC-filtered
+ * registry tools get folded in for the agent's configured user. The shape
+ * of {@link composeToolset} won't change — only the body gains a registry
+ * lookup.
+ */
+
+import { fsTools } from './tools/fsTools.ts';
+import { httpFetchTool } from './tools/httpFetchTool.ts';
+import { buildScheduleTool, type ScheduleToolDeps, type ScheduledFollowup } from './tools/scheduleTool.ts';
+import type { AgentTool } from './types.ts';
+
+export interface ComposeToolsetOpts extends ScheduleToolDeps {
+	/** When `false`, destructive tools are filtered out at composition time. */
+	allowDestructive?: boolean;
+	/** Operator-injected extras (tests, custom plugins). */
+	extraTools?: AgentTool[];
+}
+
+export interface ComposedToolset {
+	tools: AgentTool[];
+	scheduled: Map<string, ScheduledFollowup>;
+}
+
+export function composeToolset(opts: ComposeToolsetOpts): ComposedToolset {
+	const schedule = buildScheduleTool(opts);
+	const all: AgentTool[] = [...fsTools, httpFetchTool, schedule.tool, ...(opts.extraTools ?? [])];
+	const tools = opts.allowDestructive === false ? all.filter((t) => !t.destructive) : all;
+	return { tools, scheduled: schedule.pending };
+}
+
+export function toolMapByName(tools: AgentTool[]): Map<string, AgentTool> {
+	const map = new Map<string, AgentTool>();
+	for (const tool of tools) {
+		if (map.has(tool.def.name)) throw new Error(`Duplicate tool registered: ${tool.def.name}`);
+		map.set(tool.def.name, tool);
+	}
+	return map;
+}

package/core/agent/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared types for the built-in Harper Agent component (#626).
+ *
+ * `AgentMessage` mirrors `resources/models/types.ts:Message` rather than
+ * re-exporting it: the session row is durable storage and shouldn't trail
+ * shape changes in the model-access surface.
+ */
+
+import type { ToolCall, ToolDef } from '../resources/models/types.ts';
+
+export type AgentRunStatus = 'idle' | 'running' | 'awaiting_approval' | 'completed' | 'aborted' | 'error';
+
+export interface AgentMessage {
+	role: 'system' | 'user' | 'assistant' | 'tool';
+	content: string;
+	toolCalls?: ToolCall[];
+	toolCallId?: string;
+	/** Wall-clock timestamp of when this item entered the transcript. */
+	createdAt: number;
+}
+
+export interface ApprovalRequest {
+	id: string;
+	toolName: string;
+	arguments: object;
+	/** Tool-call id from the assistant message that produced this request. Used to resume execution. */
+	toolCallId: string;
+	/** Human-readable rationale for why approval is required (e.g. 'destructive', 'first_use'). */
+	reason: string;
+	createdAt: number;
+	resolved?: boolean;
+	approved?: boolean;
+	resolvedAt?: number;
+	/** Set to true once the loop has consumed the resolved approval (executed or refused). */
+	consumed?: boolean;
+}
+
+export interface AgentSessionRow {
+	session_id: string;
+	user: string;
+	status: AgentRunStatus;
+	messages: AgentMessage[];
+	pendingApprovals: ApprovalRequest[];
+	model?: string;
+	provider?: string;
+	createdAt: number;
+	updatedAt: number;
+	lastError?: string;
+}
+
+export interface AgentToolHandler {
+	(args: object, ctx: AgentToolContext): Promise<unknown>;
+}
+
+export interface AgentTool {
+	def: ToolDef;
+	handler: AgentToolHandler;
+	/** When true, invocations of this tool require an approval gate unless `autoApprove` is set. */
+	destructive?: boolean;
+}
+
+export interface AgentToolContext {
+	sessionId: string;
+	signal?: AbortSignal;
+	/** Filesystem scope roots accessible to FS tools. Read-only after composition. */
+	scopes: AgentScopes;
+}
+
+export interface AgentScopes {
+	componentsRoot: string;
+	logDir: string;
+	configDir: string;
+}
+
+export interface AgentConfig {
+	enabled: boolean;
+	provider?: string;
+	model?: string;
+	maxTurns: number;
+	maxCostUsd: number;
+	autoApprove: boolean;
+	allowDestructive: boolean;
+	user: string;
+	componentsScope?: string;
+}

package/core/benchmarks/hnsw-search.js

@@ -0,0 +1,157 @@
+'use strict';
+/**
+ * HNSW searchLayer performance benchmark — measures search latency, throughput,
+ * nodes visited per query, and recall@K against brute-force ground truth.
+ *
+ * Run (from core/ directory, after npm run build):
+ *   node benchmarks/hnsw-search.js [N_VECTORS] [DIMS] [N_QUERIES]
+ *
+ * Examples:
+ *   node benchmarks/hnsw-search.js            # defaults: 2000 x 384 x 50
+ *   node benchmarks/hnsw-search.js 5000 768   # realistic embedding workload
+ */
+
+const { performance } = require('node:perf_hooks');
+const { HierarchicalNavigableSmallWorld } = require('#src/resources/indexes/HierarchicalNavigableSmallWorld');
+const { cosineDistance } = require('#src/resources/indexes/vector');
+
+const N_VECTORS = parseInt(process.argv[2]) || 2_000;
+const DIMS = parseInt(process.argv[3]) || 384;
+const N_QUERIES = parseInt(process.argv[4]) || 50;
+const TOP_K = 10;
+
+// ---------------------------------------------------------------------------
+// Minimal in-memory store — enough interface for HierarchicalNavigableSmallWorld
+// ---------------------------------------------------------------------------
+
+class MemoryStore {
+	constructor() {
+		this._map = new Map();
+		this.encoder = { useFloat32: null };
+	}
+	_key(k) {
+		if (Array.isArray(k)) {
+			return k.map((v) => (typeof v === 'symbol' ? (Symbol.keyFor(v) ?? String(v)) : v)).join('\x00');
+		}
+		return k;
+	}
+	getSync(key) {
+		return this._map.get(this._key(key));
+	}
+	put(key, value) {
+		this._map.set(this._key(key), value);
+	}
+	remove(key) {
+		this._map.delete(this._key(key));
+	}
+	*getKeys({ reverse = false, limit = Infinity, start = -Infinity, end = Infinity } = {}) {
+		const keys = [];
+		for (const k of this._map.keys()) {
+			if (typeof k === 'number' && k >= start && k <= end) keys.push(k);
+		}
+		keys.sort((a, b) => (reverse ? b - a : a - b));
+		let n = 0;
+		for (const k of keys) {
+			if (n++ >= limit) break;
+			yield k;
+		}
+	}
+	*getRange({ start = -Infinity, end = Infinity } = {}) {
+		for (const [k, v] of this._map) {
+			if (typeof k === 'number' && k >= start && k <= end) yield { key: k, value: v };
+		}
+	}
+	getUserSharedBuffer(_name, buf) {
+		return buf;
+	}
+	getStats() {
+		let n = 0;
+		for (const k of this._map.keys()) if (typeof k === 'number') n++;
+		return { entryCount: n };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function randomVector(dims) {
+	const v = new Array(dims);
+	for (let i = 0; i < dims; i++) v[i] = Math.random() * 2 - 1;
+	return v;
+}
+
+function fmtNs(ns) {
+	if (ns < 1_000) return `${ns.toFixed(1)} ns`;
+	if (ns < 1_000_000) return `${(ns / 1_000).toFixed(2)} µs`;
+	return `${(ns / 1_000_000).toFixed(2)} ms`;
+}
+
+// ---------------------------------------------------------------------------
+// Build index
+// ---------------------------------------------------------------------------
+
+console.log(`\nHNSW benchmark — ${N_VECTORS.toLocaleString()} vectors × ${DIMS} dims, ${N_QUERIES} queries\n`);
+
+const vectors = Array.from({ length: N_VECTORS }, () => randomVector(DIMS));
+const store = new MemoryStore();
+const hnsw = new HierarchicalNavigableSmallWorld(store, { distance: 'cosine' });
+
+process.stdout.write('Building index...');
+const buildStart = performance.now();
+for (let i = 0; i < N_VECTORS; i++) {
+	hnsw.index('r' + i, vectors[i], undefined, {});
+}
+const buildMs = performance.now() - buildStart;
+console.log(` done in ${buildMs.toFixed(0)} ms  (${(buildMs / N_VECTORS).toFixed(2)} ms/insert)\n`);
+
+// ---------------------------------------------------------------------------
+// Brute-force ground truth for recall@K
+// ---------------------------------------------------------------------------
+
+const queries = Array.from({ length: N_QUERIES }, () => randomVector(DIMS));
+
+process.stdout.write('Computing brute-force ground truth...');
+const gtStart = performance.now();
+const groundTruth = queries.map((query) => {
+	const scored = vectors.map((v, i) => ({ i, d: cosineDistance(query, v) }));
+	scored.sort((a, b) => a.d - b.d);
+	return new Set(scored.slice(0, TOP_K).map((x) => x.i));
+});
+console.log(` done in ${(performance.now() - gtStart).toFixed(0)} ms\n`);
+
+// ---------------------------------------------------------------------------
+// Search benchmark
+// ---------------------------------------------------------------------------
+
+// Warmup
+for (let i = 0; i < 10; i++) {
+	hnsw.search({ target: queries[i % N_QUERIES], comparator: 'sort', descending: false }, {});
+}
+hnsw.nodesVisitedCount = 0;
+
+const searchStart = performance.now();
+const allResults = queries.map((query) => hnsw.search({ target: query, comparator: 'sort', descending: false }, {}));
+const searchMs = performance.now() - searchStart;
+
+// ---------------------------------------------------------------------------
+// Recall@K
+// ---------------------------------------------------------------------------
+
+let recallSum = 0;
+for (let i = 0; i < N_QUERIES; i++) {
+	const resultIndices = new Set(allResults[i].slice(0, TOP_K).map((r) => parseInt(r.key.slice(1))));
+	let hits = 0;
+	for (const idx of groundTruth[i]) if (resultIndices.has(idx)) hits++;
+	recallSum += hits / TOP_K;
+}
+const recall = recallSum / N_QUERIES;
+
+const avgNs = (searchMs * 1_000_000) / N_QUERIES;
+const qps = (N_QUERIES / searchMs) * 1_000;
+
+console.log('Search results:');
+console.log(`  Latency:            ${fmtNs(avgNs)}/query avg`);
+console.log(`  Throughput:         ${qps.toFixed(0)} qps`);
+console.log(`  Nodes visited/query: ${(hnsw.nodesVisitedCount / N_QUERIES).toFixed(1)}`);
+console.log(`  Recall@${TOP_K}:          ${(recall * 100).toFixed(1)}%\n`);

package/core/benchmarks/ycsb/README.md

@@ -0,0 +1,144 @@
+# YCSB-style CRUD load test
+
+A [YCSB](https://github.com/brianfrankcooper/YCSB)-style load test that drives
+CRUD operations against Harper over the **HTTP REST interface**. It boots a real
+Harper instance using [`@harperfast/integration-testing`](https://github.com/HarperFast/integration-testing-framework),
+loads a dataset, then runs the standard YCSB workloads and reports throughput and
+latency percentiles. Results are written as JSON for tracking over time (e.g. the
+nightly workflow in `.github/workflows/ycsb-nightly.yml`).
+
+## What it measures
+
+A record is a string primary key plus N string fields (YCSB default: 10 × 100 B).
+Operations map onto REST as:
+
+| Operation | REST                                         |
+| --------- | -------------------------------------------- |
+| read      | `GET /usertable/<key>`                       |
+| insert    | `PUT /usertable/<key>` (full record)         |
+| update    | `PUT /usertable/<key>` (full record replace) |
+| rmw       | `GET` then `PUT`                             |
+| scan      | `GET /usertable/?id>=<key>&limit(<n>)`       |
+
+The runner is **closed-loop**: a fixed number of in-flight requests
+(`--concurrency`) each issue their next request as soon as the previous completes,
+so throughput reflects the server rather than a fixed injection rate.
+
+### Workloads
+
+| Workload | Mix                                | Distribution |
+| -------- | ---------------------------------- | ------------ |
+| A        | 50% read / 50% update              | zipfian      |
+| B        | 95% read / 5% update               | zipfian      |
+| C        | 100% read                          | zipfian      |
+| D        | 95% read / 5% insert (read latest) | latest       |
+| E        | 95% scan / 5% insert               | zipfian      |
+| F        | 50% read / 50% read-modify-write   | zipfian      |
+
+Key distributions: `uniform`, `zipfian` (scrambled hotspot, YCSB default), and
+`latest` (biased toward recently inserted keys). Override per-run with
+`--distribution`.
+
+## Prerequisites
+
+```sh
+npm run build   # the test spawns dist/bin/harper.js
+```
+
+On macOS/Windows, configure loopback addresses once (Linux has them by default):
+
+```sh
+npx harper-integration-test-setup-loopback
+```
+
+## Running (single node)
+
+```sh
+node benchmarks/ycsb/run-single-node.mts --scale=standard
+node benchmarks/ycsb/run-single-node.mts --scale=quick --workloads=C,A
+node benchmarks/ycsb/run-single-node.mts --engine=lmdb --threads=4
+```
+
+### Scales
+
+| Scale      | records | ops/workload | concurrency |
+| ---------- | ------- | ------------ | ----------- |
+| `quick`    | 50k     | 100k         | 32          |
+| `standard` | 200k    | 500k         | 64          |
+| `heavy`    | 1M      | 4M           | 128         |
+
+### Flags
+
+`--scale` `--records` `--ops` `--concurrency` `--load-concurrency` `--fields`
+`--field-length` `--scan-max` `--warmup` `--workloads` `--distribution`
+`--engine` (`rocksdb`|`lmdb`) `--threads` `--out` `--startup-timeout`.
+Individual flags override the scale preset.
+
+## Output
+
+- Console: a per-workload table of throughput and p50/p95/p99/max latency.
+- JSON: `benchmarks/ycsb/results/ycsb-single-node-<timestamp>.json` plus a stable
+  `ycsb-single-node-latest.json`. The `results/` directory is git-ignored.
+
+The JSON includes `meta` (git commit/branch, node version, platform),
+`config` (scale, threads, engine), `load`, and per-workload throughput +
+latency stats — enough to diff runs across nights.
+
+### Trend tracking & regression alerts
+
+The nightly workflow feeds results to
+[`github-action-benchmark`](https://github.com/benchmark-action/github-action-benchmark)
+via `to-benchmark-json.mts` (throughput as bigger-is-better, p99 latency as
+smaller-is-better). History is pushed to the `gh-pages` branch and a regression
+beyond the configured threshold comments on the commit and `@`-mentions the
+maintainer. **Enable GitHub Pages on `gh-pages` to view the trend dashboard.**
+Thresholds are deliberately generous to absorb shared-runner variance — tighten
+them once the benchmark runs on a fixed/self-hosted runner.
+
+## Notes
+
+- `threads.count` is set via `HARPER_SET_CONFIG` (defaults to 4), which takes
+  precedence over the framework's default of 1.
+- Instances run with `AUTHENTICATION_AUTHORIZELOCAL=true`, so loopback requests
+  are authorized without per-request auth — the benchmark measures CRUD, not auth.
+- Only the primary key is indexed, matching the YCSB access model.
+- The schema declares `field0..field9`; keep `--fields` ≤ 10 (or edit
+  `app/schema.graphql`). Higher counts are stored as dynamic attributes, which
+  changes the load-phase write path and isn't directly comparable.
+
+### Reading the numbers (vs. reference YCSB)
+
+These are trend signals on a fixed host, not a 1:1 reproduction of the Java YCSB:
+
+- **Throughput** is _successful_ ops/sec over wall-clock time; errors are
+  reported separately. Clean runs (the expectation) report 0 errors, so the two
+  definitions coincide.
+- **Latency percentiles** use the nearest-rank method (slightly conservative vs.
+  interpolated / HdrHistogram), consistent across runs — don't compare them 1:1
+  to HdrHistogram p99s.
+- The **`latest`** distribution (workload D) is approximate: a scrambled-zipfian
+  value mod the keyspace, biased toward newest keys but with a uniform tail.
+  Faithful enough for trends, not identical to YCSB's `LatestGenerator`.
+
+## Profiling
+
+`--profile` runs the HTTP server on the main thread (`threads.count=0`) and
+sets `--cpu-prof`, so a single V8 CPU profile captures request handling.
+(Harper's worker threads use a fixed `execArgv` that `--cpu-prof` can't reach,
+hence the single-thread mode for profiling.)
+
+```sh
+node benchmarks/ycsb/run-single-node.mts --profile --records=100000 --ops=300000 --workloads=A
+node benchmarks/ycsb/analyze-profile.mts benchmarks/ycsb/results/profile
+```
+
+The analyzer prints self-time by module/category and the hottest functions. The
+profile spans startup + load + the run phase, so one-time costs (module loading,
+cert/key generation) appear alongside steady-state request handling — discount
+those when reading the results.
+
+## Cluster
+
+The 3-node cluster variant (harper-pro) reuses `workload.mts`, `restClient.mts`,
+and `harness.mts` from here, starting three connected nodes and round-robining
+load across them.