nomen-lang 0.6.8 → 0.6.9

package/audit_runtime.c

@@ -0,0 +1,50 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+// Atomic: worker threads from the pool malloc/free concurrently, and a
+// plain `long` would lose updates under that contention (showing up as
+// spurious LEAK/negative-count failures in tests that use spawns).
+static volatile long nomen_malloc_count = 0;
+
+void *nomen_malloc_wrap(unsigned long size) {
+	void *ptr = malloc(size);
+	__atomic_add_fetch(&nomen_malloc_count, 1, __ATOMIC_SEQ_CST);
+	return ptr;
+}
+
+void *nomen_calloc_wrap(unsigned long count, unsigned long size) {
+	void *ptr = calloc(count, size);
+	__atomic_add_fetch(&nomen_malloc_count, 1, __ATOMIC_SEQ_CST);
+	return ptr;
+}
+
+void *nomen_realloc_wrap(void *old_ptr, unsigned long size) {
+	if (!old_ptr) {
+		__atomic_add_fetch(&nomen_malloc_count, 1, __ATOMIC_SEQ_CST);
+	}
+	void *ptr = realloc(old_ptr, size);
+	return ptr;
+}
+
+void nomen_free_wrap(void *ptr) {
+	if (ptr) {
+		free(ptr);
+		__atomic_sub_fetch(&nomen_malloc_count, 1, __ATOMIC_SEQ_CST);
+	}
+}
+
+void *nomen_strdup_wrap(const char *s) {
+	unsigned long len = strlen(s) + 1;
+	void *ptr = malloc(len);
+	if (ptr) memcpy(ptr, s, len);
+	__atomic_add_fetch(&nomen_malloc_count, 1, __ATOMIC_SEQ_CST);
+	return ptr;
+}
+
+void nomen_audit_check(void) {
+	long count = __atomic_load_n(&nomen_malloc_count, __ATOMIC_SEQ_CST);
+	if (count != 0) {
+		printf("LEAK: %ld allocation(s)\n", count);
+	}
+}

package/core/System/StringBuilder.nm

@@ -241,7 +241,10 @@ pub struct StringBuilder {
 	}
 
 	// Finalize: null-terminate, return the byte buffer as a string, and
-	// release ownership (sets `data` to 0 so the destructor won't free it).
+	// release ownership (sets `data` to 0 so the destructor won't free it,
+	// and resets `len`/`cap` so the builder is a valid empty builder again —
+	// a stale `cap` would let a later append skip the grow and memcpy to a
+	// null buffer). Reuse after `to_string` yields a fresh builder.
 	// Explicitly `pub`: struct members default to pub, but this is the
 	// builder's primary read-back — the contract should not depend on the
 	// default.
@@ -260,6 +263,8 @@ pub struct StringBuilder {
 		((unsigned char*)(unsigned long long)self->data)[idx] = 0;
 		unsigned long long result = self->data;
 		self->data = 0;
+		self->len = 0;
+		self->cap = 0;
 		return (nomen_string){ (char*)result, (long)idx };
 		```
 		```
@@ -290,6 +295,10 @@ pub struct StringBuilder {
 		strb wzr, [x0, x1]        // data[len] = 0
 		// transfer ownership: clear self->data. x0 retains the old ptr.
 		str xzr, [x19, #8]
+		// reset the stale bookkeeping so reuse yields a valid empty builder
+		// (a stale cap would skip the append's grow against the null buffer)
+		str xzr, [x19, #16]
+		str xzr, [x19, #24]
 		// Fat-string ABI: (x0 = data, x1 = len) is already the return pair.
 		```
 	}

package/dist/index.mjs

@@ -1,13 +1,14 @@
 #! /usr/bin/env node
-import { execFileSync, execSync } from "node:child_process";
+import { execFile, execFileSync, execSync } from "node:child_process";
 import fs, { stat, unwatchFile, watch, watchFile } from "node:fs";
 import * as sp from "node:path";
 import path, { join, resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
 import { lstat, open, readdir, realpath, stat as stat$1 } from "node:fs/promises";
 import { Readable } from "node:stream";
-import { type } from "node:os";
+import os, { type } from "node:os";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 //#region ../node_modules/.pnpm/readdirp@5.1.1/node_modules/readdirp/index.js
 const EntryTypes = {
 	FILE_TYPE: "files",
@@ -15134,6 +15135,33 @@ function emit_destroy_for_scope(status, declarations_before) {
 				emit_asm(status, `ldr x19, [sp], #16\n`);
 				continue;
 			}
+			if (status.heap_array_vars?.has(decl.name)) {
+				if (status.heap_owned_string_arrays?.has(decl.name)) {
+					emit_asm(status, `str x19, [sp, #-16]!\n`);
+					emit_asm(status, `str x20, [sp, #-16]!\n`);
+					emit_var_load(status, "x0", decl.name, 8);
+					emit_asm(status, `mov x19, x0\n`);
+					emit_asm(status, `ldr x20, [x19]\n`);
+					emit_asm(status, `add x19, x19, #8\n`);
+					const loop = `.Lhosa_${decl.name}`;
+					emit_asm(status, `${loop}:\n`);
+					emit_asm(status, `cbz x20, .Lhosa_done_${decl.name}\n`);
+					emit_asm(status, `ldr x0, [x19]\n`);
+					emit_free(status);
+					emit_asm(status, `add x19, x19, #16\n`);
+					emit_asm(status, `sub x20, x20, #1\n`);
+					emit_asm(status, `b ${loop}\n`);
+					emit_asm(status, `.Lhosa_done_${decl.name}:\n`);
+					emit_var_load(status, "x0", decl.name, 8);
+					emit_free(status);
+					emit_asm(status, `ldr x20, [sp], #16\n`);
+					emit_asm(status, `ldr x19, [sp], #16\n`);
+					continue;
+				}
+				emit_var_load(status, "x0", decl.name, 8);
+				emit_free(status);
+				continue;
+			}
 			if (status.heap_strings?.has(decl.name)) {
 				emit_var_load(status, "x0", decl.name, 8);
 				emit_free(status);
@@ -33540,7 +33568,8 @@ function build_assignment_node$1(node, status, nir_rhs, nir_swap) {
 	if (!node.operator && node.left_value.node_type === "access" && node.left_value.access.node_type === "access_field" && node.right_value.node_type === "value" && node.right_value.is_moved) {
 		const access_lhs = node.left_value;
 		const field_type = access_lhs.access.type;
-		const field_struct = field_type?.name && !field_type.is_view && !field_type.is_array ? status.structs.find((s) => s.name === field_type.name && !s.is_simple_type && !s.is_class) : void 0;
+		const field_resolved = field_type?.name && !field_type.is_view && !field_type.is_array ? resolve_struct_type(field_type, status) : void 0;
+		const field_struct = field_resolved && !field_resolved.is_class ? field_resolved : void 0;
 		if (field_struct) {
 			splice_decl_from_c_scopes(status, node.right_value.value);
 			const saved_len = begin_code_scratch(status);
@@ -39017,10 +39046,31 @@ function build_access_node$1(node, status) {
 						status.code += `${ret_c} ${ctor_temp_val} = `;
 					}
 				}
+				const owned_string_recv = !ctor_temp_receiver && (node.target.node_type === "func_call" || node.target.node_type === "access" && node.target.access.node_type === "access_func") && method_type?.name === "string" && !method_type.is_view && !is_string_borrow(node.target);
+				let owned_recv_temp;
+				let owned_recv_val;
+				if (owned_string_recv) {
+					const id = status.label_counter = (status.label_counter ?? 0) + 1;
+					owned_recv_temp = `_osrecv_${id}`;
+					status.code += `({ nomen_string ${owned_recv_temp} = `;
+					{
+						const saved_suppress = status.suppress_dereference;
+						status.suppress_dereference = true;
+						build_node$1(node.target, status);
+						status.suppress_dereference = saved_suppress;
+					}
+					status.code += `; `;
+					const recv_ret_c = c_return_type((target_method ?? trait_default_func)?.return_type ?? access_func.type, status);
+					if (recv_ret_c !== "void") {
+						owned_recv_val = `_osrecvv_${id}`;
+						status.code += `${recv_ret_c} ${owned_recv_val} = `;
+					}
+				}
 				if (lambda_ret_tmp) status.code += `${lambda_ret_c} ${lambda_ret_tmp} = `;
 				status.code += `${label}(`;
 				if (!access_func.is_static) {
 					if (ctor_temp_free) status.code += ctor_temp_free;
+					else if (owned_recv_temp) status.code += owned_recv_temp;
 					else if (array_wrap) status.code += array_wrap.self_expr;
 					else {
 						const method_self_is_ref = !!target_method?.params?.some((p) => p.is_self_param && (p.is_ref || p.type?.is_ref));
@@ -39105,6 +39155,11 @@ function build_access_node$1(node, status) {
 					if (ctor_temp_val) status.code += ` ${ctor_temp_val};`;
 					status.code += ` })`;
 				}
+				if (owned_recv_temp) {
+					status.code += `; ${status.audit ? "nomen_free_wrap" : "free"}(${owned_recv_temp}.ptr);`;
+					if (owned_recv_val) status.code += ` ${owned_recv_val};`;
+					status.code += ` })`;
+				}
 				if (lambda_arg_temps.size > 0) {
 					for (const tmp of lambda_arg_temps.values()) status.code += `; ${closure_dispose_arm(tmp)}`;
 					if (lambda_ret_tmp) status.code += `; ${lambda_ret_tmp}`;
@@ -45635,7 +45690,7 @@ function build_access_method(node, access_func, status) {
 		status.last_result_is_heap = false;
 		build_node(node.target, status);
 		ensure_newline(status);
-		frees_string_receiver = method_name === "string_to_string" && status.last_result_is_heap;
+		frees_string_receiver = status.last_result_is_heap;
 		status.last_result_is_heap = false;
 		emit_asm(status, `stp x0, x1, [sp, #-16]!\n`);
 	}
@@ -62443,7 +62498,9 @@ const STRING_OPTIONS = /* @__PURE__ */ new Map([
 	["p", "platform"],
 	["lib", "lib"],
 	["l", "lib"],
-	["audit-runtime", "audit_runtime"]
+	["audit-runtime", "audit_runtime"],
+	["jobs", "jobs"],
+	["j", "jobs"]
 ]);
 const BOOLEAN_OPTIONS = /* @__PURE__ */ new Map([
 	["watch", "watch"],
@@ -62553,8 +62610,9 @@ function print_help() {
 		"  --platform, -p <name>   Target platform: macos, ios, linux, android, windows, web",
 		"  --lib, -l <path>        Path to System library directory (containing package.jsonc)",
 		"  --audit                 Audit the generated program for memory issues",
-		"  --audit-runtime <path>  Path to audit_runtime.c, linked in when --audit is set",
-		"  --release, -r           Build with optimizations (clang -O2; asm passes on aarch64)",
+		"  --audit-runtime <path>  Path to audit_runtime.c (default: auto-discovered — walk-up or the CLI-bundled copy)",
+		"  --jobs, -j <n>          For `nomen test`: max test files run in parallel (default: CPU count)",
+		"  --release, -r           Build with optimizations (clang -O2; aarch64 asm cleanup passes)",
 		"  --fast-math             Allow FP reassociation (float loop reductions vectorize on aarch64)",
 		"  --check                 For `nomen format`: report files that would change",
 		"  -h, --help              Show this help"
@@ -62902,6 +62960,9 @@ function find_bundled(filename) {
 	const candidates = !cli_root.includes("node_modules") ? [path.join(repo_root, filename), path.join(cli_root, filename)] : [path.join(cli_root, filename), path.join(repo_root, filename)];
 	for (const c of candidates) if (fs.existsSync(c)) return path.resolve(c);
 }
+function find_bundled_audit_runtime() {
+	return find_bundled("src/audit_runtime.c") ?? find_bundled("audit_runtime.c");
+}
 /**
 * `nomen init <name>`: scaffold a new project under `./<name>` with a sensible
 * starting layout (package.jsonc, src/main.nm, a starter test, README and an
@@ -62980,6 +63041,7 @@ function outfile_for(input_path, is_test, out) {
 //#endregion
 //#region src/test.ts
 const RECORD_PREFIX = "\\nomen|";
+const execFile_async = promisify(execFile);
 /** Recursively collect `*.test.nm` files under `root`, skipping build output. */
 function collect_test_files(root) {
 	const out = [];
@@ -63129,7 +63191,7 @@ function extract_leaks(stdout) {
 * Compile one `*.test.nm` file (with the generated harness) and run it,
 * returning its parsed records and any crash info.
 */
-function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime, release = false, cwd) {
+async function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime, release = false, cwd) {
 	const start = performance.now();
 	const source_text = fs.readFileSync(entry_path, "utf8");
 	const harness = generate_harness(extract_test_functions(source_text), extract_bench_functions(source_text));
@@ -63170,7 +63232,7 @@ function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime,
 	if (!fs.existsSync(buildDir)) fs.mkdirSync(buildDir, { recursive: true });
 	let audit_obj;
 	if (audit) {
-		const runtime_src = audit_runtime ? path.resolve(audit_runtime) : find_audit_runtime(path.dirname(resolved));
+		const runtime_src = audit_runtime ? path.resolve(audit_runtime) : find_audit_runtime(path.dirname(resolved)) ?? find_bundled_audit_runtime();
 		if (!runtime_src || !fs.existsSync(runtime_src)) {
 			result.ok = false;
 			result.phase = "setup";
@@ -63179,7 +63241,7 @@ function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime,
 			return result;
 		}
 		audit_obj = path.join(buildDir, "audit_runtime.o");
-		execFileSync("clang", [
+		await execFile_async("clang", [
 			"-c",
 			runtime_src,
 			"-o",
@@ -63208,14 +63270,7 @@ function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime,
 	if (audit_obj) link_args.push(audit_obj);
 	if (platform === "macos" || platform === "ios") link_args.push("-framework", "CoreGraphics", "-framework", "Foundation", "-framework", "AppKit", "-lobjc");
 	try {
-		execFileSync("clang", link_args, {
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			]
-		});
+		await execFile_async("clang", link_args, { encoding: "utf8" });
 	} catch (err) {
 		const stderr = err.stderr ? err.stderr.toString() : err.message ?? "";
 		result.ok = false;
@@ -63227,17 +63282,12 @@ function run_test_file(entry_path, lib_path, arch, audit = false, audit_runtime,
 	let runStdout = "";
 	let crashed;
 	try {
-		runStdout = execFileSync(outfile, [], {
+		runStdout = (await execFile_async(outfile, [], {
 			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
 			timeout: 3e4,
 			maxBuffer: 16777216,
 			cwd: cwd ?? process.cwd()
-		});
+		})).stdout;
 	} catch (err) {
 		runStdout = err.stdout ? err.stdout.toString() : "";
 		if (err.signal === "SIGTERM") crashed = "test binary timed out after 30s";
@@ -63296,10 +63346,16 @@ function report_file(result) {
 		for (const line of result.other) console.log(C.dim(`   ${line}`));
 	}
 }
+/** The default concurrency for `runTests` when no `jobs` is given. */
+function default_jobs() {
+	const n = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+	return Math.max(1, n);
+}
 /**
 * Locate audit_runtime.c for an audited test build: an explicit path wins,
 * otherwise walk up from `dir` looking for a `src/audit_runtime.c` (the same
-* convention the run/build commands use).
+* convention the run/build commands use). When both miss, the caller falls
+* back to the CLI-bundled runtime (`find_bundled_audit_runtime`).
 */
 function find_audit_runtime(dir) {
 	let cur = dir;
@@ -63312,19 +63368,25 @@ function find_audit_runtime(dir) {
 	}
 }
 /** Discover, run, and report every `*.test.nm` under `root`. */
-function runTests(root, options = {}) {
+async function runTests(root, options = {}) {
 	const arch = options.arch ?? "aarch64";
 	const lib = resolve_lib_for(root);
 	const files = collect_test_files(root).filter((f) => !options.filter || options.filter.test(f));
 	console.log(`Found ${files.length} test file(s)\n`);
 	const startTime = performance.now();
 	const binary_cwd = path.resolve(root);
-	const results = [];
-	for (const file of files) {
-		const result = run_test_file(file, lib, arch, options.audit, options.audit_runtime, options.release, binary_cwd);
-		report_file(result);
-		results.push(result);
-	}
+	const jobs = Math.max(1, Math.min(options.jobs ?? default_jobs(), files.length));
+	const results = new Array(files.length);
+	let next = 0;
+	const worker = async () => {
+		for (;;) {
+			const i = next++;
+			if (i >= files.length) return;
+			results[i] = await run_test_file(files[i], lib, arch, options.audit, options.audit_runtime, options.release, binary_cwd);
+		}
+	};
+	await Promise.all(Array.from({ length: jobs }, worker));
+	for (const result of results) report_file(result);
 	const elapsed = performance.now() - startTime;
 	const totalFiles = results.length;
 	const totalFilesFailed = results.reduce((a, r) => a + (r.ok ? 0 : 1), 0);
@@ -63425,12 +63487,13 @@ try {
 	if (command === "test") {
 		const root = args.in ?? process.cwd();
 		const filter = args.filter ? new RegExp(args.filter) : void 0;
-		const ok = runTests(root, {
+		const ok = await runTests(root, {
 			arch: args.arch ?? "aarch64",
 			filter,
 			audit: args.audit,
 			audit_runtime: args.audit_runtime,
-			release: args.release
+			release: args.release,
+			jobs: args.jobs !== void 0 ? parseInt(args.jobs, 10) : void 0
 		});
 		process.exit(ok ? 0 : 1);
 	}
@@ -63541,6 +63604,7 @@ function resolve_audit_runtime(config, input_path) {
 		if (parent === dir) break;
 		dir = parent;
 	}
+	return find_bundled_audit_runtime();
 }
 function compile_audit_runtime(config, input_path, buildDir) {
 	const runtime_src = resolve_audit_runtime(config, input_path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nomen-lang",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "The CLI for the Nomen programming language.",
   "keywords": [],
   "license": "ISC",
@@ -17,7 +17,8 @@
     "dist",
     "src",
     "core",
-    "NOMEN_AGENTS.md"
+    "NOMEN_AGENTS.md",
+    "audit_runtime.c"
   ],
   "type": "module",
   "devDependencies": {

package/src/args.ts

@@ -13,6 +13,8 @@ export interface Args {
 	audit_runtime?: string;
 	check: boolean;
 	release: boolean;
+	/** `nomen test` concurrency (max test files in flight); default = CPU count. */
+	jobs?: string;
 	/** Opt in to FP reassociation: float reductions vectorize under NEON
 	 *  (results may differ in the last ulp vs the scalar loop). */
 	fast_math: boolean;
@@ -39,6 +41,8 @@ const STRING_OPTIONS: Map<string, string> = new Map([
 	["lib", "lib"],
 	["l", "lib"],
 	["audit-runtime", "audit_runtime"],
+	["jobs", "jobs"],
+	["j", "jobs"],
 ]);
 
 const BOOLEAN_OPTIONS: Map<string, string> = new Map([
@@ -174,8 +178,9 @@ export function print_help(): void {
 			"  --platform, -p <name>   Target platform: macos, ios, linux, android, windows, web",
 			"  --lib, -l <path>        Path to System library directory (containing package.jsonc)",
 			"  --audit                 Audit the generated program for memory issues",
-			"  --audit-runtime <path>  Path to audit_runtime.c, linked in when --audit is set",
-			"  --release, -r           Build with optimizations (clang -O2; asm passes on aarch64)",
+			"  --audit-runtime <path>  Path to audit_runtime.c (default: auto-discovered — walk-up or the CLI-bundled copy)",
+			"  --jobs, -j <n>          For `nomen test`: max test files run in parallel (default: CPU count)",
+			"  --release, -r           Build with optimizations (clang -O2; aarch64 asm cleanup passes)",
 			"  --fast-math             Allow FP reassociation (float loop reductions vectorize on aarch64)",
 			"  --check                 For `nomen format`: report files that would change",
 			"  -h, --help              Show this help",

package/src/index.ts

@@ -13,7 +13,7 @@ import parse from "../../src/parse.ts";
 import { parse_args, print_help, type Args } from "./args.ts";
 import { run_docs } from "./docs.ts";
 import render_errors, { render_warnings } from "./format_errors.ts";
-import { find_bundled, run_init } from "./init.ts";
+import { find_bundled, find_bundled_audit_runtime, run_init } from "./init.ts";
 import { build_dir_for, outfile_for } from "./paths.ts";
 import { runTests } from "./test.ts";
 import type Config from "./types/Config.ts";
@@ -104,12 +104,13 @@ try {
 		const root = args.in ?? process.cwd();
 		const filter = args.filter ? new RegExp(args.filter) : undefined;
 		const arch = args.arch ?? "aarch64";
-		const ok = runTests(root, {
+		const ok = await runTests(root, {
 			arch,
 			filter,
 			audit: args.audit,
 			audit_runtime: args.audit_runtime,
 			release: args.release,
+			jobs: args.jobs !== undefined ? parseInt(args.jobs, 10) : undefined,
 		});
 		process.exit(ok ? 0 : 1);
 	}
@@ -283,7 +284,10 @@ function resolve_audit_runtime(config: Config, input_path: string): string | und
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return undefined;
+	// Neither the config nor the walk-up found it: fall back to the runtime
+	// bundled with the CLI (live repo copy in the dev tree, shipped copy when
+	// published) so `--audit` works outside the nomen checkout with no flag.
+	return find_bundled_audit_runtime();
 }
 
 function compile_audit_runtime(config: Config, input_path: string, buildDir: string): string {

package/src/init.ts

@@ -85,6 +85,16 @@ export function find_bundled(filename: string): string | undefined {
 	return undefined;
 }
 
+// The audit runtime for `--audit` builds: the dev tree's LIVE copy
+// (repo_root/src/audit_runtime.c — a stale bundled snapshot must not shadow
+// it, same posture as the cli/core rule above), else the copy shipped at the
+// package root by `scripts/bundle-assets.mjs` in a published install. Lets
+// `nomen test/run --audit` work outside the nomen checkout with no
+// --audit-runtime flag.
+export function find_bundled_audit_runtime(): string | undefined {
+	return find_bundled("src/audit_runtime.c") ?? find_bundled("audit_runtime.c");
+}
+
 /**
  * `nomen init <name>`: scaffold a new project under `./<name>` with a sensible
  * starting layout (package.jsonc, src/main.nm, a starter test, README and an

package/src/test.ts

@@ -1,17 +1,26 @@
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 
 import build, { default_platform } from "../../src/build.ts";
 import join from "../../src/join.ts";
 import { get_library } from "../../src/lib.ts";
 import parse from "../../src/parse.ts";
-import { find_bundled } from "./init.ts";
+import { find_bundled, find_bundled_audit_runtime } from "./init.ts";
 import { build_dir_for } from "./paths.ts";
 
 const RECORD_PREFIX = "\\nomen|";
 
+// Promise-returning `execFile`: `nomen test` builds and runs each `*.test.nm`
+// file in its own build folder and its own process, so the (latency-bound)
+// clang/link/run subprocesses overlap across files instead of serializing.
+// A rejected error carries the same `.stdout` / `.stderr` / `.signal` /
+// `.code` fields the previous synchronous `execFileSync` catch sites read.
+const execFile_async = promisify(execFile);
+
 // A discovered test function: `pub func <name> = (ref Tester t)`.
 export interface TestFunction {
 	name: string;
@@ -272,7 +281,7 @@ export function extract_leaks(stdout: string): string[] {
  * Compile one `*.test.nm` file (with the generated harness) and run it,
  * returning its parsed records and any crash info.
  */
-export function run_test_file(
+export async function run_test_file(
 	entry_path: string,
 	lib_path: string | undefined,
 	arch: string,
@@ -280,7 +289,7 @@ export function run_test_file(
 	audit_runtime?: string,
 	release = false,
 	cwd?: string,
-): TestFileResult {
+): Promise<TestFileResult> {
 	const start = performance.now();
 	const source_text = fs.readFileSync(entry_path, "utf8");
 	const tests = extract_test_functions(source_text);
@@ -339,9 +348,13 @@ export function run_test_file(
 	// "LEAK: N allocation(s)" when the balance is nonzero.
 	let audit_obj: string | undefined;
 	if (audit) {
+		// Explicit flag wins; else walk up from the test file (a nomen
+		// checkout's src/audit_runtime.c); else the runtime bundled with the
+		// CLI (live repo copy in the dev tree, shipped copy when published)
+		// so `--audit` works outside the nomen checkout with no flag.
 		const runtime_src = audit_runtime
 			? path.resolve(audit_runtime)
-			: find_audit_runtime(path.dirname(resolved));
+			: (find_audit_runtime(path.dirname(resolved)) ?? find_bundled_audit_runtime());
 		if (!runtime_src || !fs.existsSync(runtime_src)) {
 			result.ok = false;
 			result.phase = "setup";
@@ -351,7 +364,7 @@ export function run_test_file(
 			return result;
 		}
 		audit_obj = path.join(buildDir, "audit_runtime.o");
-		execFileSync("clang", ["-c", runtime_src, "-o", audit_obj]);
+		await execFile_async("clang", ["-c", runtime_src, "-o", audit_obj]);
 	}
 	const platform = default_platform();
 	// Match the run/build command's emission: ObjC-bearing sources (GUI code
@@ -401,10 +414,7 @@ export function run_test_file(
 		);
 	}
 	try {
-		execFileSync("clang", link_args, {
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "pipe"],
-		});
+		await execFile_async("clang", link_args, { encoding: "utf8" });
 	} catch (err: any) {
 		const stderr = err.stderr ? err.stderr.toString() : (err.message ?? "");
 		result.ok = false;
@@ -424,13 +434,13 @@ export function run_test_file(
 	let runStdout = "";
 	let crashed: string | undefined;
 	try {
-		runStdout = execFileSync(outfile, [], {
+		const run = await execFile_async(outfile, [], {
 			encoding: "utf8",
-			stdio: ["ignore", "pipe", "pipe"],
 			timeout: 30_000,
 			maxBuffer: 16 * 1024 * 1024,
 			cwd: cwd ?? process.cwd(),
 		});
+		runStdout = run.stdout;
 	} catch (err: any) {
 		runStdout = err.stdout ? err.stdout.toString() : "";
 		if (err.signal === "SIGTERM") {
@@ -545,12 +555,27 @@ export interface RunTestsOptions {
 	audit?: boolean;
 	audit_runtime?: string;
 	release?: boolean;
+	/**
+	 * Maximum test files built and run concurrently. Each file compiles into
+	 * its own build folder and runs in its own process, so the latency-bound
+	 * clang/link/run steps overlap across files. Defaults to the machine's
+	 * available parallelism; 1 forces the historical sequential order.
+	 */
+	jobs?: number;
+}
+
+/** The default concurrency for `runTests` when no `jobs` is given. */
+export function default_jobs(): number {
+	const n =
+		typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+	return Math.max(1, n);
 }
 
 /**
  * Locate audit_runtime.c for an audited test build: an explicit path wins,
  * otherwise walk up from `dir` looking for a `src/audit_runtime.c` (the same
- * convention the run/build commands use).
+ * convention the run/build commands use). When both miss, the caller falls
+ * back to the CLI-bundled runtime (`find_bundled_audit_runtime`).
  */
 function find_audit_runtime(dir: string): string | undefined {
 	let cur = dir;
@@ -565,7 +590,7 @@ function find_audit_runtime(dir: string): string | undefined {
 }
 
 /** Discover, run, and report every `*.test.nm` under `root`. */
-export function runTests(root: string, options: RunTestsOptions = {}): boolean {
+export async function runTests(root: string, options: RunTestsOptions = {}): Promise<boolean> {
 	const arch = options.arch ?? "aarch64";
 	const lib = resolve_lib_for(root);
 	const files = collect_test_files(root).filter((f) => !options.filter || options.filter.test(f));
@@ -577,20 +602,33 @@ export function runTests(root: string, options: RunTestsOptions = {}): boolean {
 	// fixture paths resolve there no matter where the CLI was invoked from.
 	const binary_cwd = path.resolve(root);
 
-	const results: TestFileResult[] = [];
-	for (const file of files) {
-		const result = run_test_file(
-			file,
-			lib,
-			arch,
-			options.audit,
-			options.audit_runtime,
-			options.release,
-			binary_cwd,
-		);
-		report_file(result);
-		results.push(result);
-	}
+	// Bounded-concurrency pool: at most `jobs` files are in flight. The
+	// parse/build halves are synchronous (no internal awaits), so they run
+	// atomically on the main thread between the subprocess awaits — the
+	// compiler's in-process state never interleaves. Results are collected by
+	// file INDEX and reported after the pool drains, so the report stays in
+	// discovery order regardless of completion order (and stdout isn't
+	// interleaved).
+	const jobs = Math.max(1, Math.min(options.jobs ?? default_jobs(), files.length));
+	const results: TestFileResult[] = new Array(files.length);
+	let next = 0;
+	const worker = async (): Promise<void> => {
+		for (;;) {
+			const i = next++;
+			if (i >= files.length) return;
+			results[i] = await run_test_file(
+				files[i],
+				lib,
+				arch,
+				options.audit,
+				options.audit_runtime,
+				options.release,
+				binary_cwd,
+			);
+		}
+	};
+	await Promise.all(Array.from({ length: jobs }, worker));
+	for (const result of results) report_file(result);
 
 	const elapsed = performance.now() - startTime;
 	const totalFiles = results.length;