xbintsc 0.2.9 → 0.3.1

package/src/codegen/values.ts

@@ -6,34 +6,34 @@
  * emits these constants directly into LLVM IR, so this module (together with
  * runtime/rt.h) is the single source of truth for the representation.
  *
- * The constants are written as pre-computed signed 64-bit decimal literals
- * rather than BigInt expressions, and `numberLiteral` derives the raw bits of a
- * double with plain arithmetic. That keeps this module free of BigInt and
- * typed-array APIs so the compiler can be compiled by itself on every platform.
+ * BigInts are available both to the host (Node) running the compiler and to
+ * the compiler once self-hosted, so the constants below are written as BigInt
+ * literals and `numberLiteral` derives a double's raw bits with BigInt
+ * arithmetic. `i64` normalises any 64-bit pattern to the signed decimal form
+ * LLVM expects.
  */
 
-/** `0xffff000000000000` as a signed i64. */
-export const XT_TAG_MASK = "-281474976710656";
-/** `0xfff8000000000000` as a signed i64. */
-export const XT_NUMBER_MASK = "-2251799813685248";
+export const XT_TAG_MASK = 0xffff000000000000n;
+export const XT_NUMBER_MASK = 0xfff8000000000000n;
 
-export const XT_UNDEFINED = "-2251799813685248"; // 0xfff8000000000000
-export const XT_NULL = "-1970324836974592"; // 0xfff9000000000000
-export const XT_FALSE = "-1688849860263936"; // 0xfffa000000000000
-export const XT_TRUE = "-1407374883553280"; // 0xfffb000000000000
-export const XT_STRING = "-1125899906842624"; // 0xfffc000000000000
-export const XT_OBJECT = "-844424930131968"; // 0xfffd000000000000
-export const XT_ARRAY = "-562949953421312"; // 0xfffe000000000000
-export const XT_FUNCTION = "-281474976710656"; // 0xffff000000000000
+export const XT_UNDEFINED = 0xfff8000000000000n;
+export const XT_NULL = 0xfff9000000000000n;
+export const XT_FALSE = 0xfffa000000000000n;
+export const XT_TRUE = 0xfffa000000000001n;
+export const XT_BIGINT = 0xfffb000000000000n;
+export const XT_STRING = 0xfffc000000000000n;
+export const XT_OBJECT = 0xfffd000000000000n;
+export const XT_ARRAY = 0xfffe000000000000n;
+export const XT_FUNCTION = 0xffff000000000000n;
 
 /** Render a 64-bit constant the way LLVM expects signed i64 literals. */
-export function i64(value: string): string {
-  return value;
+export function i64(value: bigint): string {
+  return BigInt.asIntN(64, value).toString();
 }
 
 /** The raw 64 bits of an IEEE-754 double, as a signed i64 literal. */
 export function numberLiteral(value: number): string {
-  if (value !== value) return "9221120237041090560"; // 0x7ff8000000000000 (NaN)
+  if (value !== value) return i64(0x7ff8000000000000n);
   const negative = value < 0 || (value === 0 && 1 / value < 0);
   const abs = negative ? -value : value;
   let high: number;
@@ -61,45 +61,10 @@ export function numberLiteral(value: number): string {
     low = mantissa % 0x100000000;
   }
   if (negative) high += 0x80000000;
-  return signedDecimal(high >>> 0, low >>> 0);
+  const bits = (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
+  return i64(bits);
 }
 
 export function booleanLiteral(value: boolean): string {
-  return value ? XT_TRUE : XT_FALSE;
-}
-
-/** Two's-complement (high, low) 32-bit halves as a signed decimal string. */
-function signedDecimal(high: number, low: number): string {
-  if (high >= 0x80000000) {
-    let h = (~high) >>> 0;
-    let l = (~low) >>> 0;
-    l = (l + 1) >>> 0;
-    if (l === 0) h = (h + 1) >>> 0;
-    return "-" + unsignedDecimal(h, l);
-  }
-  return unsignedDecimal(high, low);
-}
-
-/** Unsigned 64-bit `high * 2^32 + low` as a decimal string. */
-function unsignedDecimal(high: number, low: number): string {
-  const digits: number[] = [];
-  let h = high;
-  if (h === 0) digits.push(0);
-  while (h > 0) {
-    digits.push(h % 10);
-    h = Math.floor(h / 10);
-  }
-  let carry = low;
-  for (let i = 0; i < digits.length; i++) {
-    const current = digits[i]! * 4294967296 + carry;
-    digits[i] = current % 10;
-    carry = Math.floor(current / 10);
-  }
-  while (carry > 0) {
-    digits.push(carry % 10);
-    carry = Math.floor(carry / 10);
-  }
-  let out = "";
-  for (let i = digits.length - 1; i >= 0; i--) out += digits[i]!;
-  return out;
+  return i64(value ? XT_TRUE : XT_FALSE);
 }

package/src/diagnostics/diagnostic.ts

@@ -25,6 +25,7 @@ export enum DiagnosticCode {
   DuplicateIdentifier = 3001,
   CannotFindName = 3002,
   IllegalRedeclaration = 3003,
+  CannotAssignToConst = 3004,
 
   // Checker 4xxx
   TypeMismatch = 4001,

package/src/diagnostics/source.ts

@@ -80,20 +80,15 @@ export class SourceFile {
  * and stable across platforms which is exactly what the incremental cache
  * needs. Collision resistance is not a security property here.
  */
-export function hashText(text: string, seed = 0): string {
-  // Two independent 32-bit FNV-1a lanes give a wide, stable fingerprint
-  // without relying on BigInt, which the compiler cannot assume at runtime.
-  let a = (0xcbf29ce4 ^ seed) >>> 0;
-  let b = (0x84222325 ^ seed) >>> 0;
-  const prime = 0x01000193;
+export function hashText(text: string, seed = 0xcbf29ce484222325n): string {
+  let hash = seed;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
   for (let i = 0; i < text.length; i++) {
-    const code = text.charCodeAt(i);
-    a = Math.imul(a ^ (code & 0xff), prime) >>> 0;
-    a = Math.imul(a ^ (code >>> 8), prime) >>> 0;
-    b = Math.imul(b ^ (code >>> 8), prime) >>> 0;
-    b = Math.imul(b ^ (code & 0xff), prime) >>> 0;
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = (hash * prime) & mask;
   }
-  return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+  return hash.toString(16).padStart(16, "0");
 }
 
 /** Combine several hashes/strings into one stable fingerprint. */

package/src/driver/compiler.ts

@@ -18,10 +18,11 @@ import { bundleModules } from "./modules.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { BuildCache, hashParts } from "./cache.js";
 import { findRuntimeDir } from "./paths.js";
+import { findRuntimeLibrary } from "./runtime-lib.js";
+import { resolveToolchain } from "./toolchain-provider.js";
 import {
   compileC,
   compileIr,
-  findClang,
   link,
   realRunner,
   type Runner,
@@ -43,6 +44,8 @@ export interface BuildOptions {
   readonly extensions?: ExtensionRegistry;
   readonly runner?: Runner;
   readonly clang?: string;
+  /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
+  readonly preferPrebuilt?: boolean;
   readonly write?: boolean;
 }
 
@@ -189,14 +192,14 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   }
 
   // -- toolchain -----------------------------------------------------------
-  const clang = options.clang ?? findClang(runner);
-  const runtimeDir = findRuntimeDir();
+  const toolchain = options.clang
+    ? { clang: options.clang, linkerArgs: [] as string[], env: {} as Record<string, string> }
+    : resolveToolchain(runner);
+  const clang = toolchain.clang;
   mkdirSync(cacheDir, { recursive: true });
 
-  const { runtimeObjects, extensionObjects } = ensureRuntimeObjects(runner, clang, runtimeDir, cacheDir, registry);
-
   const objectPath = emit === "obj" ? outputPath : resolve(outDir, baseName + ".o");
-  compileIr(runner, { clang, irPath, objectPath, optimize });
+  compileIr(runner, { clang, irPath, objectPath, optimize, env: toolchain.env });
 
   if (emit === "obj") {
     cache.record(cacheKey, outputs);
@@ -204,12 +207,28 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, irPath, cached: false, diagnostics: [], ir };
   }
 
+  const runtimeDir = findRuntimeDir();
+  const { runtimeObjects, extensionObjects } = ensureRuntimeObjects(
+    runner,
+    clang,
+    runtimeDir,
+    cacheDir,
+    registry,
+    options.preferPrebuilt ?? true,
+    toolchain.env,
+  );
+
   link(runner, {
     clang,
     objectPaths: [objectPath, ...runtimeObjects, ...extensionObjects],
     outputPath,
-    linkerFlags: [...(process.platform === "win32" ? ["-lws2_32"] : ["-lm"]), ...registry.linkerFlags()],
+    linkerFlags: [
+      ...toolchain.linkerArgs,
+      ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm"]),
+      ...registry.linkerFlags(),
+    ],
     optimize,
+    env: toolchain.env,
   });
 
   cache.record(cacheKey, outputs);
@@ -223,9 +242,10 @@ interface RuntimeObjects {
 }
 
 /** Core runtime translation units (each compiled and cached independently). */
-const RUNTIME_SOURCES = [
+export const RUNTIME_SOURCES = [
   "xt_alloc.c",
   "xt_values.c",
+  "xt_bigint.c",
   "xt_containers.c",
   "xt_stdlib.c",
   "xt_stdlib2.c",
@@ -238,6 +258,10 @@ const RUNTIME_SOURCES = [
 /**
  * Compile the core runtime and every extension source, reusing cached object
  * files keyed on the C source hash. Returns the object paths to link.
+ *
+ * When `preferPrebuilt` is set, a shipped static archive
+ * (`runtime/lib/<os>-<arch>/{core,ext_<name>}.a`) is used instead of compiling
+ * that group's C sources. Missing archives fall back to compiling the sources.
  */
 function ensureRuntimeObjects(
   runner: Runner,
@@ -245,15 +269,18 @@ function ensureRuntimeObjects(
   runtimeDir: string,
   cacheDir: string,
   registry: ExtensionRegistry,
+  preferPrebuilt: boolean,
+  env: Record<string, string>,
 ): RuntimeObjects {
-  /* Runtime objects depend on the shared headers (rt.h/rt_internal.h/...),
-     so a header change must invalidate every cached object. Hash them all. */
+  /* Runtime objects depend on the shared headers (rt.h/rt_internal.h/...) and
+     the `#include`d implementation fragments (`.inc`), so any change to them
+     must invalidate every cached object. Hash them all. */
   const headerParts: string[] = [];
   const collectHeaders = (dir: string): void => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const full = join(dir, entry.name);
       if (entry.isDirectory()) collectHeaders(full);
-      else if (entry.name.endsWith(".h")) headerParts.push(readFileSync(full, "utf8"));
+      else if (entry.name.endsWith(".h") || entry.name.endsWith(".inc")) headerParts.push(readFileSync(full, "utf8"));
     }
   };
   collectHeaders(runtimeDir);
@@ -264,16 +291,32 @@ function ensureRuntimeObjects(
     const key = hashParts(["runtime", COMPILER_VERSION, tag, headerStamp, body, clang, process.platform]);
     const objectPath = join(cacheDir, `${tag}-${key}.o`);
     if (!existsSync(objectPath)) {
-      compileC(runner, clang, sourcePath, objectPath, runtimeDir);
+      compileC(runner, clang, sourcePath, objectPath, runtimeDir, env);
     }
     return objectPath;
   };
 
-  const runtimeObjects = RUNTIME_SOURCES.map((source) =>
-    compileOne(join(runtimeDir, source), basename(source, ".c")),
-  );
-  const extensionObjects = registry
-    .runtimeSources()
-    .map((sourcePath, index) => compileOne(sourcePath, `ext_${index}_${basename(sourcePath, ".c")}`));
+  const coreArchive = preferPrebuilt ? findRuntimeLibrary("core") : undefined;
+  const runtimeObjects = coreArchive
+    ? [coreArchive]
+    : RUNTIME_SOURCES.map((source) => compileOne(join(runtimeDir, source), basename(source, ".c")));
+
+  const extensionObjects: string[] = [];
+  const seen = new Set<string>();
+  for (const extension of registry.all()) {
+    const sources = extension.runtimeSources ? extension.runtimeSources() : [];
+    if (sources.length === 0) continue;
+    const archive = preferPrebuilt ? findRuntimeLibrary(`ext_${extension.name}`) : undefined;
+    if (archive) {
+      extensionObjects.push(archive);
+      continue;
+    }
+    for (const sourcePath of sources) {
+      const dedupeKey = resolve(sourcePath);
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      extensionObjects.push(compileOne(sourcePath, `ext_${extensionObjects.length}_${basename(sourcePath, ".c")}`));
+    }
+  }
   return { runtimeObjects, extensionObjects };
 }

package/src/driver/index.ts

@@ -1,4 +1,19 @@
 export { build, compileString, COMPILER_VERSION, type BuildOptions, type BuildResult, type EmitKind } from "./compiler.js";
 export { BuildCache, hashParts, hashString } from "./cache.js";
-export { findRuntimeDir, findPackageRoot } from "./paths.js";
-export { findClang, realRunner, ToolchainError, type Runner } from "./toolchain.js";
+export { findRuntimeDir, findPackageRoot, findVendorDir, vendorRootDir, platformSlug, releaseArchiveBase, releaseArchiveExtension } from "./paths.js";
+export {
+  toolchainDownload,
+  toolchainSupportLibraries,
+  LLVM_VERSION,
+  LLVM_MINGW_VERSION,
+  type ToolchainDownload,
+  type SupportLibrary,
+} from "./toolchain-download.js";
+export { findRuntimeLibrary, runtimeLibDir } from "./runtime-lib.js";
+export {
+  findClang,
+  realRunner,
+  ToolchainError,
+  type Runner,
+} from "./toolchain.js";
+export { resolveToolchain, type ResolvedToolchain, type ToolchainSource } from "./toolchain-provider.js";

package/src/driver/paths.ts

@@ -11,6 +11,9 @@ export function findRuntimeDir(): string {
   const candidates = [
     resolve(here, "../../runtime"),
     resolve(here, "../../../runtime"),
+    // Packaged release layout: `<root>/bin/xbintsc` next to `<root>/runtime`.
+    resolve(here, "../runtime"),
+    resolve(here, "runtime"),
     resolve(process.cwd(), "runtime"),
   ];
   for (const candidate of candidates) {
@@ -22,3 +25,54 @@ export function findRuntimeDir(): string {
 export function findPackageRoot(): string {
   return resolve(findRuntimeDir(), "..");
 }
+
+/** `<package>/vendor` — where a bundled toolchain is assembled (may not exist). */
+export function vendorRootDir(): string {
+  return resolve(findPackageRoot(), "vendor");
+}
+
+/** Platform-architecture slug, e.g. `darwin-arm64`, `linux-x64`, `win32-x64`. */
+export function platformSlug(): string {
+  return `${process.platform}-${process.arch}`;
+}
+
+/**
+ * Base name (no extension) of a packaged release archive, e.g.
+ * `xbintsc-linux-x64`. Matches the top-level directory inside the archive.
+ */
+export function releaseArchiveBase(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): string {
+  return `xbintsc-${platform}-${arch}`;
+}
+
+/**
+ * Extension for a release archive. `.tar.zst` when a `zstd` binary is available
+ * (smaller, faster), otherwise the universally supported `.tar.gz`.
+ */
+export function releaseArchiveExtension(useZstd: boolean): string {
+  return useZstd ? ".tar.zst" : ".tar.gz";
+}
+
+/**
+ * Directory that may hold a toolchain shipped next to the package:
+ * `<package>/vendor/<os>-<arch>` (or a generic `vendor/`). Undefined when none
+ * is present, in which case the driver falls back to the system PATH.
+ */
+export function findVendorDir(): string | undefined {
+  const roots: string[] = [];
+  try {
+    roots.push(findPackageRoot());
+  } catch {
+    // `runtime/` may be absent (e.g. a bare `emit` install); vendor is optional.
+  }
+  roots.push(resolve(here, "../../.."), resolve(here, "../.."), process.cwd());
+  for (const root of roots) {
+    const specific = join(root, "vendor", platformSlug());
+    if (existsSync(specific)) return specific;
+    const generic = join(root, "vendor");
+    if (existsSync(generic)) return generic;
+  }
+  return undefined;
+}

package/src/driver/runtime-lib.ts

@@ -0,0 +1,32 @@
+/**
+ * Prebuilt runtime archives.
+ *
+ * The C runtime is normally compiled once into a static archive by
+ * `npm run runtime`:
+ *
+ *   runtime/lib/<os>-<arch>/core.a        (the core `xt_*.c` runtime)
+ *   runtime/lib/<os>-<arch>/ext_<name>.a  (per-extension sources, e.g. ext_node.a)
+ *
+ * Shipping these lets `build` link without compiling C, and shortens the first
+ * build. When an archive is missing the driver transparently falls back to
+ * compiling the `.c` sources, so the archives are an optimization, not a hard
+ * dependency.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findRuntimeDir, platformSlug } from "./paths.js";
+
+/** Directory holding the prebuilt archives for the current host. */
+export function runtimeLibDir(): string {
+  return join(findRuntimeDir(), "lib", platformSlug());
+}
+
+/** Absolute path to a prebuilt archive (`core`, `ext_node`, …), if present. */
+export function findRuntimeLibrary(name: string): string | undefined {
+  const base = join(runtimeLibDir(), name);
+  for (const candidate of [`${base}.a`, `${base}.lib`]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}

package/src/driver/toolchain-download.ts

@@ -0,0 +1,108 @@
+/**
+ * Which toolchain xbintsc bundles for each host.
+ *
+ * The end goal is that `build` needs no user-installed compiler. Per the
+ * recorded decisions (see `doc/requirements.md`):
+ *
+ *   Linux   -> the official LLVM release (clang + lld + llvm-ar)
+ *   Windows -> llvm-mingw (clang + lld + the MinGW-w64 sysroot/CRT/import libs)
+ *   macOS   -> nothing; the Xcode Command Line Tools are the prerequisite
+ *
+ * This module only maps a host to a pinned download; the actual fetch lives in
+ * `scripts/fetch-toolchain.ts`.
+ */
+
+/** Pinned LLVM release used for the Linux bundle. */
+export const LLVM_VERSION = "18.1.8";
+/** Pinned llvm-mingw release used for the Windows bundle. */
+export const LLVM_MINGW_VERSION = "20260908";
+
+export interface ToolchainDownload {
+  /** Download URL. */
+  readonly url: string;
+  /** Suggested local file name for the archive. */
+  readonly archive: string;
+  /** Archive type. Both are unpacked with `tar` (bsdtar reads zip). */
+  readonly kind: "tar.xz" | "zip";
+  /** Leading path segments to strip while extracting. */
+  readonly stripComponents: number;
+}
+
+/**
+ * The toolchain to bundle for a host, or undefined when the host's own SDK is
+ * used instead (macOS: the Xcode Command Line Tools).
+ */
+export function toolchainDownload(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): ToolchainDownload | undefined {
+  if (platform === "linux") {
+    if (arch === "x64") {
+      return {
+        url: `https://github.com/llvm/llvm-project/releases/download/llvmorg-${LLVM_VERSION}/clang+llvm-${LLVM_VERSION}-x86_64-linux-gnu-ubuntu-18.04.tar.xz`,
+        archive: `clang+llvm-${LLVM_VERSION}-x86_64-linux-gnu.tar.xz`,
+        kind: "tar.xz",
+        stripComponents: 1,
+      };
+    }
+    if (arch === "arm64") {
+      return {
+        url: `https://github.com/llvm/llvm-project/releases/download/llvmorg-${LLVM_VERSION}/clang+llvm-${LLVM_VERSION}-aarch64-linux-gnu.tar.xz`,
+        archive: `clang+llvm-${LLVM_VERSION}-aarch64-linux-gnu.tar.xz`,
+        kind: "tar.xz",
+        stripComponents: 1,
+      };
+    }
+    return undefined;
+  }
+
+  if (platform === "win32" && arch === "x64") {
+    return {
+      url: `https://github.com/mstorsjo/llvm-mingw/releases/download/${LLVM_MINGW_VERSION}/llvm-mingw-${LLVM_MINGW_VERSION}-ucrt-x86_64.zip`,
+      archive: `llvm-mingw-${LLVM_MINGW_VERSION}-ucrt-x86_64.zip`,
+      kind: "zip",
+      stripComponents: 1,
+    };
+  }
+
+  // macOS (and any other host) uses the system SDK; nothing to bundle.
+  return undefined;
+}
+
+export interface SupportLibrary {
+  /** Candidate download URLs, tried in order. */
+  readonly urls: readonly string[];
+  /** Local file name for the downloaded `.deb`. */
+  readonly archive: string;
+  /** Path inside the extracted `.deb` data tree. */
+  readonly member: string;
+  /** File name placed in `vendor/<os>-<arch>/lib/`. */
+  readonly dest: string;
+}
+
+/**
+ * Extra shared libraries the bundled toolchain needs but that are not part of
+ * the OS C library. The official Linux LLVM build links the legacy
+ * `libtinfo.so.5` soname, which current distributions no longer ship, so we
+ * bundle it (from the Ubuntu `libtinfo5` package) into `vendor/<os>-<arch>/lib`
+ * and point `LD_LIBRARY_PATH` at that directory.
+ */
+export function toolchainSupportLibraries(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): readonly SupportLibrary[] {
+  if (platform === "linux" && arch === "x64") {
+    return [
+      {
+        urls: [
+          "https://security.ubuntu.com/ubuntu/pool/main/n/ncurses/libtinfo5_6.1-1ubuntu1.18.04.1_amd64.deb",
+          "https://archive.ubuntu.com/ubuntu/pool/main/n/ncurses/libtinfo5_6.1-1ubuntu1.18.04.1_amd64.deb",
+        ],
+        archive: "libtinfo5.deb",
+        member: "lib/x86_64-linux-gnu/libtinfo.so.5.9",
+        dest: "libtinfo.so.5",
+      },
+    ];
+  }
+  return [];
+}

package/src/driver/toolchain-provider.ts

@@ -0,0 +1,91 @@
+/**
+ * Toolchain selection.
+ *
+ * xbintsc shells out to a clang-compatible driver for three jobs: lowering LLVM
+ * IR to an object, compiling the C runtime, and linking. This module decides
+ * *which* driver to use, in a fixed priority order, so a bundled toolchain can
+ * shadow the system one without touching the driver code:
+ *
+ *   1. an explicit `xbintsc_CLANG` / `xbintsc_TOOLCHAIN`
+ *   2. a toolchain shipped next to the package (`vendor/<os>-<arch>/bin`)
+ *   3. the system `PATH` (`findClang`)
+ *
+ * Extra linker arguments (for example `-fuse-ld=lld`) can be supplied through
+ * `xbintsc_LINKER_ARGS`.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findVendorDir } from "./paths.js";
+import { findClang, realRunner, type Runner } from "./toolchain.js";
+
+export type ToolchainSource = "env" | "vendor" | "system";
+
+export interface ResolvedToolchain {
+  /** Path or name of the clang-compatible driver to invoke. */
+  readonly clang: string;
+  /** Where the driver came from. */
+  readonly source: ToolchainSource;
+  /** Extra arguments to pass to the link step. */
+  readonly linkerArgs: readonly string[];
+  /**
+   * Extra environment for the toolchain subprocesses, merged over the current
+   * environment. Used to point `LD_LIBRARY_PATH` at bundled shared libraries
+   * (for example the legacy `libtinfo.so.5` the official Linux build needs).
+   */
+  readonly env: Record<string, string>;
+}
+
+function works(runner: Runner, command: string, env?: Record<string, string>): boolean {
+  try {
+    return runner.run(command, ["--version"], env ? { env } : undefined).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function linkerArgs(fallback: readonly string[]): string[] {
+  const raw = process.env.xbintsc_LINKER_ARGS;
+  if (raw) return raw.split(" ").filter((part) => part.length > 0);
+  return [...fallback];
+}
+
+/**
+ * Environment overrides for a bundled toolchain. The official Linux build links
+ * the removed `libtinfo.so.5` soname, so when we ship it under `vendor/lib/` we
+ * prepend that directory to the dynamic linker search path.
+ */
+function vendorEnv(vendor: string): Record<string, string> {
+  const libDir = join(vendor, "lib");
+  if (process.platform !== "linux" || !existsSync(libDir)) return {};
+  const existing = process.env.LD_LIBRARY_PATH;
+  return { LD_LIBRARY_PATH: existing ? libDir + ":" + existing : libDir };
+}
+
+/** Resolve the toolchain that `build` should use. See the module docblock. */
+export function resolveToolchain(runner: Runner = realRunner): ResolvedToolchain {
+  const explicit = process.env.xbintsc_CLANG ?? process.env.xbintsc_TOOLCHAIN;
+  if (explicit && works(runner, explicit)) {
+    return { clang: explicit, source: "env", linkerArgs: linkerArgs([]), env: {} };
+  }
+
+  const vendor = findVendorDir();
+  if (vendor) {
+    const env = vendorEnv(vendor);
+    const names = process.platform === "win32" ? ["clang.exe", "clang"] : ["clang"];
+    for (const name of names) {
+      const candidate = join(vendor, "bin", name);
+      if (existsSync(candidate) && works(runner, candidate, env)) {
+        // A bundled toolchain ships `ld.lld`, so prefer lld over any system linker.
+        return {
+          clang: candidate,
+          source: "vendor",
+          linkerArgs: linkerArgs(["-fuse-ld=lld"]),
+          env,
+        };
+      }
+    }
+  }
+
+  return { clang: findClang(runner), source: "system", linkerArgs: linkerArgs([]), env: {} };
+}