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

package/core/benchmarks/ycsb/analyze-profile.mts

@@ -0,0 +1,120 @@
+/**
+ * Summarizes V8 .cpuprofile files produced by `run-single-node.mts --profile`.
+ * Prints the hottest functions by self time and a per-module breakdown, which
+ * is the input for performance recommendations.
+ *
+ *   node benchmarks/ycsb/analyze-profile.mts benchmarks/ycsb/results/profile [topN]
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+interface CallFrame {
+	functionName: string;
+	url: string;
+	lineNumber: number;
+}
+interface ProfileNode {
+	id: number;
+	callFrame: CallFrame;
+	hitCount?: number;
+	children?: number[];
+}
+interface CpuProfile {
+	nodes: ProfileNode[];
+	samples: number[];
+	timeDeltas: number[];
+}
+
+function moduleOf(url: string): string {
+	if (!url) return '(builtin/native)';
+	if (url.startsWith('node:')) return url;
+	const nm = url.lastIndexOf('node_modules/');
+	if (nm >= 0) {
+		const rest = url.slice(nm + 'node_modules/'.length).split('/');
+		return rest[0].startsWith('@') ? `${rest[0]}/${rest[1]}` : rest[0];
+	}
+	const dist = url.indexOf('/dist/');
+	if (dist >= 0) {
+		// dist/<area>/file.js — bucket by the top-level area (resources, server, ...)
+		return `harper/${url.slice(dist + '/dist/'.length).split('/')[0]}`;
+	}
+	return url.split('/').slice(-2).join('/');
+}
+
+// V8 synthetic frames — (program), (idle), (garbage collector) — carry their label in
+// functionName with an empty url; bucket them on the name so they don't fold into native.
+function moduleOfFrame(frame: CallFrame): string {
+	return frame.functionName.startsWith('(') ? frame.functionName : moduleOf(frame.url);
+}
+
+function fnKey(frame: CallFrame): string {
+	const mod = moduleOf(frame.url);
+	const name = frame.functionName || '(anonymous)';
+	return `${name}  [${mod}]`;
+}
+
+async function analyzeFile(
+	path: string
+): Promise<{ self: Map<string, number>; module: Map<string, number>; total: number }> {
+	const profile = JSON.parse(await readFile(path, 'utf8')) as CpuProfile;
+	const byId = new Map<number, ProfileNode>();
+	for (const node of profile.nodes) byId.set(node.id, node);
+
+	const selfMicros = new Map<number, number>();
+	for (let i = 0; i < profile.samples.length; i++) {
+		const id = profile.samples[i];
+		selfMicros.set(id, (selfMicros.get(id) ?? 0) + (profile.timeDeltas[i] ?? 0));
+	}
+
+	const self = new Map<string, number>();
+	const module = new Map<string, number>();
+	let total = 0;
+	for (const [id, micros] of selfMicros) {
+		const node = byId.get(id);
+		if (!node) continue;
+		const m = Math.max(0, micros);
+		total += m;
+		const key = fnKey(node.callFrame);
+		self.set(key, (self.get(key) ?? 0) + m);
+		const mod = moduleOfFrame(node.callFrame);
+		module.set(mod, (module.get(mod) ?? 0) + m);
+	}
+	return { self, module, total };
+}
+
+function topEntries(map: Map<string, number>, total: number, n: number): string[] {
+	return [...map.entries()]
+		.sort((a, b) => b[1] - a[1])
+		.slice(0, n)
+		.map(
+			([key, micros]) =>
+				`  ${((micros / total) * 100).toFixed(1).padStart(5)}%  ${(micros / 1000).toFixed(0).padStart(7)} ms  ${key}`
+		);
+}
+
+async function main(): Promise<void> {
+	const dir = process.argv[2];
+	const topN = Number(process.argv[3] ?? 30);
+	if (!dir) throw new Error('usage: analyze-profile.mts <profile-dir> [topN]');
+	const files = (await readdir(dir)).filter((f) => f.endsWith('.cpuprofile'));
+	if (files.length === 0) throw new Error(`no .cpuprofile files in ${dir}`);
+
+	const self = new Map<string, number>();
+	const module = new Map<string, number>();
+	let total = 0;
+	for (const file of files) {
+		const r = await analyzeFile(join(dir, file));
+		for (const [k, v] of r.self) self.set(k, (self.get(k) ?? 0) + v);
+		for (const [k, v] of r.module) module.set(k, (module.get(k) ?? 0) + v);
+		total += r.total;
+	}
+
+	process.stdout.write(`\nCPU profile summary — ${files.length} file(s), ${(total / 1000).toFixed(0)} ms of samples\n`);
+	process.stdout.write(`\nBy module / category (self time):\n${topEntries(module, total, 20).join('\n')}\n`);
+	process.stdout.write(`\nTop ${topN} functions (self time):\n${topEntries(self, total, topN).join('\n')}\n`);
+}
+
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});

package/core/benchmarks/ycsb/app/config.yaml

@@ -0,0 +1,3 @@
+rest: true # expose all exported resources over the HTTP REST interface
+graphqlSchema:
+  files: '*.graphql' # define the usertable schema

package/core/benchmarks/ycsb/app/schema.graphql

@@ -0,0 +1,17 @@
+# YCSB record table: a string primary key plus 10 unindexed string fields
+# (the YCSB default record shape). Only the primary key is indexed, so reads,
+# updates and key-range scans all go through the primary index — matching the
+# YCSB access model.
+type usertable @table @export {
+	id: ID @primaryKey
+	field0: String
+	field1: String
+	field2: String
+	field3: String
+	field4: String
+	field5: String
+	field6: String
+	field7: String
+	field8: String
+	field9: String
+}

package/core/benchmarks/ycsb/harness.mts

@@ -0,0 +1,328 @@
+/**
+ * Shared YCSB benchmark harness: CLI option parsing, the load + run-phase
+ * driver, results assembly, and console reporting. Both the single-node
+ * (harper) and 3-node cluster (harper-pro) entry points call into this so the
+ * workload definitions and result shape stay identical across them.
+ */
+import { parseArgs } from 'node:util';
+import { execFileSync } from 'node:child_process';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { join } from 'node:path';
+import {
+	WORKLOADS,
+	KeyState,
+	runOperations,
+	type DistributionName,
+	type LatencyStats,
+	type OperationType,
+	type PhaseResult,
+} from './workload.mts';
+import { createRestExecutor } from './restClient.mts';
+
+export interface BenchmarkConfig {
+	records: number;
+	opsPerWorkload: number;
+	concurrency: number;
+	loadConcurrency: number;
+	fieldCount: number;
+	fieldLength: number;
+	maxScanLength: number;
+	warmupOps: number;
+	workloads: string[];
+	distribution?: DistributionName;
+	table: string;
+}
+
+export interface ParsedOptions {
+	config: BenchmarkConfig;
+	scale: string;
+	engine: string;
+	threads: number;
+	nodeCount: number;
+	out: string;
+	startupTimeoutMs: number;
+	settleMs: number;
+	profile: boolean;
+}
+
+const SCALE_PRESETS: Record<string, { records: number; opsPerWorkload: number; concurrency: number }> = {
+	quick: { records: 50_000, opsPerWorkload: 100_000, concurrency: 32 },
+	standard: { records: 200_000, opsPerWorkload: 500_000, concurrency: 64 },
+	heavy: { records: 1_000_000, opsPerWorkload: 4_000_000, concurrency: 128 },
+};
+
+const DEFAULT_WORKLOAD_ORDER = ['C', 'B', 'A', 'F', 'D', 'E'];
+
+export function parseOptions(argv: string[]): ParsedOptions {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			'scale': { type: 'string', default: 'standard' },
+			'records': { type: 'string' },
+			'ops': { type: 'string' },
+			'concurrency': { type: 'string' },
+			'load-concurrency': { type: 'string' },
+			'fields': { type: 'string', default: '10' },
+			'field-length': { type: 'string', default: '100' },
+			'scan-max': { type: 'string', default: '100' },
+			'warmup': { type: 'string' },
+			'workloads': { type: 'string', default: DEFAULT_WORKLOAD_ORDER.join(',') },
+			'distribution': { type: 'string' },
+			'engine': { type: 'string', default: 'rocksdb' },
+			'threads': { type: 'string', default: '4' },
+			'nodes': { type: 'string', default: '3' },
+			'out': { type: 'string', default: join(import.meta.dirname, 'results') },
+			'startup-timeout': { type: 'string', default: '120000' },
+			'settle-ms': { type: 'string', default: '0' },
+			'profile': { type: 'boolean', default: false },
+		},
+		allowPositionals: false,
+	});
+
+	const preset = SCALE_PRESETS[values.scale as string];
+	if (!preset) throw new Error(`unknown scale "${values.scale}" (expected ${Object.keys(SCALE_PRESETS).join(', ')})`);
+
+	const opsPerWorkload = values.ops ? Number(values.ops) : preset.opsPerWorkload;
+	const concurrency = values.concurrency ? Number(values.concurrency) : preset.concurrency;
+	const workloads = (values.workloads as string).split(',').map((w) => w.trim().toUpperCase());
+	for (const w of workloads) {
+		if (!WORKLOADS[w])
+			throw new Error(`unknown workload "${w}" (expected one of ${Object.keys(WORKLOADS).join(', ')})`);
+	}
+
+	const config: BenchmarkConfig = {
+		records: values.records ? Number(values.records) : preset.records,
+		opsPerWorkload,
+		concurrency,
+		loadConcurrency: values['load-concurrency'] ? Number(values['load-concurrency']) : concurrency,
+		fieldCount: Number(values.fields),
+		fieldLength: Number(values['field-length']),
+		maxScanLength: Number(values['scan-max']),
+		warmupOps: values.warmup ? Number(values.warmup) : Math.min(opsPerWorkload, 20_000),
+		workloads,
+		distribution: values.distribution as DistributionName | undefined,
+		table: 'usertable',
+	};
+
+	return {
+		config,
+		scale: values.scale as string,
+		engine: values.engine as string,
+		threads: Number(values.threads),
+		nodeCount: Number(values.nodes),
+		out: values.out as string,
+		startupTimeoutMs: Number(values['startup-timeout']),
+		settleMs: Number(values['settle-ms']),
+		profile: values.profile as boolean,
+	};
+}
+
+function keyWidth(config: BenchmarkConfig): number {
+	return Math.max(10, String(config.records + config.opsPerWorkload).length);
+}
+
+export interface WorkloadResult {
+	name: string;
+	description: string;
+	distribution: DistributionName;
+	ops: number;
+	errors: number;
+	elapsedMs: number;
+	throughput: number;
+	latency: Partial<Record<OperationType, LatencyStats>>;
+}
+
+export interface BenchmarkResults {
+	meta: Record<string, unknown>;
+	config: BenchmarkConfig & { engine: string; threads: number; nodeCount: number; baseUrls: string[] };
+	load: { ops: number; errors: number; elapsedMs: number; throughput: number };
+	workloads: WorkloadResult[];
+}
+
+function gitInfo(): { commit: string; branch: string } {
+	const read = (args: string[]): string => {
+		try {
+			return execFileSync('git', args, { encoding: 'utf8' }).trim();
+		} catch {
+			return 'unknown';
+		}
+	};
+	return { commit: read(['rev-parse', 'HEAD']), branch: read(['rev-parse', '--abbrev-ref', 'HEAD']) };
+}
+
+/**
+ * Runs the load phase then each selected workload against the given base URLs
+ * (one for single-node, several for a cluster — requests round-robin across
+ * them). Returns the assembled results; does not manage instance lifecycle.
+ */
+export async function runBenchmark(
+	baseUrls: string[],
+	options: ParsedOptions,
+	extraMeta: Record<string, unknown> = {}
+): Promise<BenchmarkResults> {
+	const { config } = options;
+	const width = keyWidth(config);
+	const shape = { fieldCount: config.fieldCount, fieldLength: config.fieldLength };
+	const executor = createRestExecutor({
+		baseUrls,
+		table: config.table,
+		maxSockets: Math.max(config.concurrency, config.loadConcurrency),
+	});
+
+	const log = (msg: string) => process.stdout.write(`${msg}\n`);
+
+	try {
+		// --- Load phase: insert `records` records with sequential keys ---
+		log(`\n[load] inserting ${config.records.toLocaleString()} records (concurrency ${config.loadConcurrency})...`);
+		const loadKeys = new KeyState({
+			distribution: 'uniform',
+			initialKeyCount: 0,
+			keyWidth: width,
+			shape,
+			maxScanLength: config.maxScanLength,
+		});
+		const loadResult = await runOperations({
+			opCount: config.records,
+			concurrency: config.loadConcurrency,
+			mix: { insert: 1 },
+			executor,
+			keys: loadKeys,
+			onProgress: (done, total) => log(`  loaded ${done.toLocaleString()} / ${total.toLocaleString()}`),
+		});
+		log(
+			`[load] ${loadResult.throughput.toFixed(0)} records/sec, ${loadResult.errors} errors, ${(loadResult.elapsedMs / 1000).toFixed(1)}s`
+		);
+
+		// --- Settle: let async replication converge before reading (cluster runs) ---
+		if (options.settleMs > 0) {
+			log(`[settle] waiting ${options.settleMs}ms for replication to converge...`);
+			await delay(options.settleMs);
+		}
+
+		// --- Optional warmup (discarded) ---
+		if (config.warmupOps > 0) {
+			log(`[warmup] ${config.warmupOps.toLocaleString()} read ops (discarded)...`);
+			await runOperations({
+				opCount: config.warmupOps,
+				concurrency: config.concurrency,
+				mix: { read: 1 },
+				executor,
+				keys: new KeyState({
+					distribution: 'zipfian',
+					initialKeyCount: config.records,
+					keyWidth: width,
+					shape,
+					maxScanLength: config.maxScanLength,
+				}),
+			});
+		}
+
+		// --- Run phase: each selected workload against the loaded dataset ---
+		const workloadResults: WorkloadResult[] = [];
+		for (const name of config.workloads) {
+			const spec = WORKLOADS[name];
+			const distribution = config.distribution ?? spec.distribution;
+			log(`\n[workload ${name}] ${spec.description} — ${distribution}, ${config.opsPerWorkload.toLocaleString()} ops`);
+			const keys = new KeyState({
+				distribution,
+				initialKeyCount: config.records,
+				keyWidth: width,
+				shape,
+				maxScanLength: config.maxScanLength,
+			});
+			const result: PhaseResult = await runOperations({
+				opCount: config.opsPerWorkload,
+				concurrency: config.concurrency,
+				mix: spec.mix,
+				executor,
+				keys,
+				onProgress: (done, total) => log(`  ${name}: ${done.toLocaleString()} / ${total.toLocaleString()}`),
+			});
+			log(`[workload ${name}] ${result.throughput.toFixed(0)} ops/sec, ${result.errors} errors`);
+			workloadResults.push({
+				name,
+				description: spec.description,
+				distribution,
+				ops: result.ops,
+				errors: result.errors,
+				elapsedMs: result.elapsedMs,
+				throughput: result.throughput,
+				latency: result.latency,
+			});
+		}
+
+		const { commit, branch } = gitInfo();
+		return {
+			meta: {
+				timestamp: new Date().toISOString(),
+				gitCommit: commit,
+				gitBranch: branch,
+				nodeVersion: process.version,
+				platform: `${process.platform}-${process.arch}`,
+				...extraMeta,
+			},
+			config: {
+				...config,
+				engine: options.engine,
+				threads: options.threads,
+				nodeCount: baseUrls.length,
+				baseUrls,
+			},
+			load: {
+				ops: loadResult.ops,
+				errors: loadResult.errors,
+				elapsedMs: loadResult.elapsedMs,
+				throughput: loadResult.throughput,
+			},
+			workloads: workloadResults,
+		};
+	} finally {
+		executor.close();
+	}
+}
+
+export async function writeResults(results: BenchmarkResults, outDir: string, label: string): Promise<string> {
+	await mkdir(outDir, { recursive: true });
+	const stamp = results.meta.timestamp as string;
+	const file = join(outDir, `ycsb-${label}-${stamp.replace(/[:.]/g, '-')}.json`);
+	await writeFile(file, JSON.stringify(results, null, 2));
+	await writeFile(join(outDir, `ycsb-${label}-latest.json`), JSON.stringify(results, null, 2));
+	return file;
+}
+
+function fmt(n: number): string {
+	return n.toFixed(2).padStart(9);
+}
+
+export function printReport(results: BenchmarkResults): void {
+	const lines: string[] = [];
+	lines.push('');
+	lines.push('='.repeat(78));
+	lines.push(
+		`YCSB results — ${results.config.nodeCount} node(s), threads.count=${results.config.threads}, ${results.config.engine}`
+	);
+	lines.push(
+		`records=${results.config.records.toLocaleString()}  ops/workload=${results.config.opsPerWorkload.toLocaleString()}  concurrency=${results.config.concurrency}`
+	);
+	lines.push('='.repeat(78));
+	lines.push(`load: ${results.load.throughput.toFixed(0)} records/sec (${results.load.errors} errors)`);
+	lines.push('');
+	lines.push(
+		`${'workload'.padEnd(10)}${'op'.padEnd(8)}${'thrput/s'.padStart(10)}${'p50 ms'.padStart(10)}${'p95 ms'.padStart(10)}${'p99 ms'.padStart(10)}${'max ms'.padStart(10)}`
+	);
+	lines.push('-'.repeat(78));
+	for (const wl of results.workloads) {
+		const header = `${wl.name.padEnd(10)}`;
+		const types = Object.keys(wl.latency) as OperationType[];
+		types.forEach((type, i) => {
+			const s = wl.latency[type]!;
+			const prefix = i === 0 ? header : ' '.repeat(10);
+			const thr = i === 0 ? wl.throughput.toFixed(0).padStart(10) : ''.padStart(10);
+			lines.push(`${prefix}${type.padEnd(8)}${thr}${fmt(s.p50)}${fmt(s.p95)}${fmt(s.p99)}${fmt(s.max)}`);
+		});
+		if (wl.errors > 0) lines.push(`${' '.repeat(10)}(${wl.errors} errors)`);
+	}
+	lines.push('='.repeat(78));
+	process.stdout.write(lines.join('\n') + '\n');
+}

package/core/benchmarks/ycsb/restClient.mts

@@ -0,0 +1,120 @@
+/**
+ * REST transport for the YCSB workload runner.
+ *
+ * Maps CRUD operations onto Harper's HTTP REST interface:
+ *   read   -> GET    /<table>/<key>
+ *   insert -> PUT    /<table>/<key>   (full record)
+ *   update -> PUT    /<table>/<key>   (full record replace)
+ *   rmw    -> GET then PUT
+ *   scan   -> GET    /<table>/?id>=<startKey>&limit(<count>)
+ *
+ * Uses node:http(s) with a keep-alive agent (no external dependency) so the
+ * client's connection pool is sized to the configured concurrency and never
+ * becomes the bottleneck. Across multiple base URLs it round-robins requests,
+ * which is how the cluster benchmark spreads load over nodes.
+ */
+import http from 'node:http';
+import https from 'node:https';
+import { Buffer } from 'node:buffer';
+import type { OpExecutor } from './workload.mts';
+
+interface Endpoint {
+	lib: typeof http | typeof https;
+	hostname: string;
+	port: number;
+	agent: http.Agent;
+}
+
+export interface RestClientOptions {
+	baseUrls: string[];
+	table: string;
+	maxSockets: number;
+	auth?: { username: string; password: string };
+	/** Per-request timeout; a hung socket otherwise blocks a closed-loop worker forever. */
+	requestTimeoutMs?: number;
+}
+
+export interface RestExecutor extends OpExecutor {
+	close(): void;
+}
+
+export function createRestExecutor(options: RestClientOptions): RestExecutor {
+	const { table } = options;
+	const requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+	const authHeader = options.auth
+		? 'Basic ' + Buffer.from(`${options.auth.username}:${options.auth.password}`).toString('base64')
+		: undefined;
+
+	const endpoints: Endpoint[] = options.baseUrls.map((raw) => {
+		const url = new URL(raw);
+		const secure = url.protocol === 'https:';
+		const lib = secure ? https : http;
+		return {
+			lib,
+			hostname: url.hostname,
+			port: Number(url.port) || (secure ? 443 : 80),
+			agent: new lib.Agent({ keepAlive: true, maxSockets: options.maxSockets, maxFreeSockets: options.maxSockets }),
+		};
+	});
+
+	let cursor = 0;
+	const nextEndpoint = (): Endpoint => endpoints[cursor++ % endpoints.length];
+
+	function send(method: string, path: string, body?: Buffer): Promise<Buffer> {
+		const endpoint = nextEndpoint();
+		const headers: Record<string, string> = {};
+		if (authHeader) headers.authorization = authHeader;
+		if (body) {
+			headers['content-type'] = 'application/json';
+			headers['content-length'] = String(body.length);
+		}
+		return new Promise<Buffer>((resolve, reject) => {
+			const req = endpoint.lib.request(
+				{ hostname: endpoint.hostname, port: endpoint.port, path, method, headers, agent: endpoint.agent },
+				(res) => {
+					const chunks: Buffer[] = [];
+					res.on('data', (chunk: Buffer) => chunks.push(chunk));
+					res.on('end', () => {
+						const status = res.statusCode ?? 0;
+						if (status >= 200 && status < 300) {
+							resolve(Buffer.concat(chunks));
+						} else {
+							reject(new Error(`${method} ${path} -> ${status}: ${Buffer.concat(chunks).toString().slice(0, 200)}`));
+						}
+					});
+					res.on('error', reject);
+				}
+			);
+			req.on('error', reject);
+			req.setTimeout(requestTimeoutMs, () =>
+				req.destroy(new Error(`${method} ${path} timed out after ${requestTimeoutMs}ms`))
+			);
+			if (body) req.write(body);
+			req.end();
+		});
+	}
+
+	const recordPath = (key: string): string => `/${table}/${key}`;
+
+	return {
+		async read(key: string): Promise<void> {
+			await send('GET', recordPath(key));
+		},
+		async insert(key: string, record: Record<string, string>): Promise<void> {
+			await send('PUT', recordPath(key), Buffer.from(JSON.stringify(record)));
+		},
+		async update(key: string, record: Record<string, string>): Promise<void> {
+			await send('PUT', recordPath(key), Buffer.from(JSON.stringify(record)));
+		},
+		async readModifyWrite(key: string, record: Record<string, string>): Promise<void> {
+			await send('GET', recordPath(key));
+			await send('PUT', recordPath(key), Buffer.from(JSON.stringify(record)));
+		},
+		async scan(startKey: string, count: number): Promise<void> {
+			await send('GET', `/${table}/?id>=${startKey}&limit(${count})`);
+		},
+		close(): void {
+			for (const endpoint of endpoints) endpoint.agent.destroy();
+		},
+	};
+}

package/core/benchmarks/ycsb/run-single-node.mts

@@ -0,0 +1,97 @@
+/**
+ * YCSB-style CRUD load test against a single local Harper (core) instance.
+ *
+ * Boots one Harper instance via @harperfast/integration-testing with the
+ * `usertable` app pre-installed, then drives the YCSB load + run phases over
+ * the HTTP REST interface and writes JSON results.
+ *
+ * Build Harper first (npm run build), then run e.g.:
+ *   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
+ *
+ * See harness.mts (parseOptions) for the full flag list.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { createHarperContext, setupHarperWithFixture, teardownHarper } from '@harperfast/integration-testing';
+import { parseOptions, runBenchmark, writeResults, printReport } from './harness.mts';
+
+const REPO_ROOT = join(import.meta.dirname, '..', '..');
+const HARPER_BIN = join(REPO_ROOT, 'dist', 'bin', 'harper.js');
+const APP_DIR = join(import.meta.dirname, 'app');
+
+async function waitForRoute(url: string, deadlineMs: number): Promise<void> {
+	const deadline = Date.now() + deadlineMs;
+	while (Date.now() < deadline) {
+		try {
+			const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+			await res.body?.cancel(); // always drain so the socket is freed
+			// Require 2xx: after startup the HTTP stack is up but the usertable route may not be
+			// registered yet, and a 404 from the router would falsely pass a < 500 check.
+			if (res.status >= 200 && res.status < 300) return;
+		} catch {
+			// not accepting connections yet (or this probe timed out)
+		}
+		await delay(250);
+	}
+	throw new Error(`timed out waiting for ${url}`);
+}
+
+async function main(): Promise<void> {
+	const options = parseOptions(process.argv.slice(2));
+	const ctx = createHarperContext('ycsb-single-node');
+
+	// In --profile mode, run the HTTP server on the main thread (threads.count=0)
+	// so a single NODE_OPTIONS --cpu-prof captures request handling — Harper's
+	// worker threads use a fixed execArgv that --cpu-prof can't reach.
+	const threads = options.profile ? 0 : options.threads;
+	// This config is passed as HARPER_SET_CONFIG, which takes precedence over (and filters out)
+	// the framework's hard-coded CLI args — so threads.count and logging.level here override the
+	// framework defaults of --THREADS_COUNT=1 and --LOGGING_LEVEL=debug. The latter matters:
+	// debug logging under load would be a major measurement confound.
+	const config: Record<string, unknown> = {
+		threads: { count: threads },
+		analytics: { aggregatePeriod: -1 }, // analytics aggregation is noisy under load
+		logging: { level: 'warn' },
+	};
+	// Set the engine explicitly (not only when non-default) so the run is pinned to the
+	// requested engine even if Harper's default changes, matching the reported config.
+	const env: Record<string, string> = { HARPER_STORAGE_ENGINE: options.engine };
+	let profileDir: string | undefined;
+	if (options.profile) {
+		profileDir = join(options.out, 'profile');
+		await mkdir(profileDir, { recursive: true });
+		env.NODE_OPTIONS = `--cpu-prof --cpu-prof-dir=${profileDir}`;
+	}
+
+	console.log(
+		`Starting Harper (threads.count=${threads}, engine=${options.engine}${options.profile ? ', profiling' : ''})...`
+	);
+	await setupHarperWithFixture(ctx, APP_DIR, {
+		harperBinPath: HARPER_BIN,
+		config,
+		env,
+		startupTimeoutMs: options.startupTimeoutMs,
+	});
+
+	const { httpURL } = ctx.harper;
+	try {
+		await waitForRoute(`${httpURL}/${options.config.table}/`, 30_000);
+		console.log(`Harper ready at ${httpURL}`);
+		const results = await runBenchmark([httpURL], options);
+		const file = await writeResults(results, options.out, 'single-node');
+		printReport(results);
+		console.log(`\nResults written to ${file}`);
+	} finally {
+		await teardownHarper(ctx);
+		console.log('Harper stopped.');
+		if (profileDir) console.log(`CPU profile(s) in ${profileDir}`);
+	}
+}
+
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});