peachsim 0.1.1625 → 0.1.1640

package/src/swift-submit.ts

@@ -20,6 +20,7 @@
  * Browser-safe: node-only submitters live beside their call sites.
  */
 
+import { isRecord } from './is-record'
 import {
   isSwiftMetalLibrarySources,
   type SwiftMetalLibrarySource,
@@ -32,6 +33,10 @@ export const SWIFT_HMR_PATH = '/__peach/swift-hmr'
 
 // shared with the compile service; collection enforces these before reading.
 export const MAX_SWIFT_COMPILE_FILES = 256
+/** how long one swift build may run when the caller asks for no budget. */
+export const DEFAULT_SWIFT_COMPILE_BUILD_MS = 10 * 60_000
+/** the longest build budget a caller may request. */
+export const MAX_SWIFT_COMPILE_BUILD_MS = 60 * 60_000
 export const MAX_SWIFT_COMPILE_SOURCE_BYTES = 2 * 1024 * 1024
 export const MAX_SWIFT_COMPILE_RESOURCES = 128
 export const MAX_SWIFT_COMPILE_RESOURCE_BYTES = 2 * 1024 * 1024
@@ -104,7 +109,8 @@ export const MAX_SWIFT_COMPILE_IMAGE_TOTAL_BYTES = 16 * 1024 * 1024
 // 45: confirmation dialogs present from a measured `presentationSource`, and a
 // refreshable's pull ends on the host's `refreshEnded` request.
 // 46: ImageRenderer produces shared CoreGraphics pixels through the isolated raster host.
-export const SWIFT_HOST_ABI = 46
+// 47: backing-layer masks composite the view, border and children through mask alpha.
+export const SWIFT_HOST_ABI = 47
 
 export interface SwiftImageUpload {
   /** the raster file picked for the asset (has the extension). */
@@ -237,6 +243,11 @@ export type SwiftCompileSubmit = (work: {
   entry: string
   /** the directory-derived id of the One package. */
   packageId: string
+  /**
+   * how long the build may run, up to `MAX_SWIFT_COMPILE_BUILD_MS`; absent means
+   * the default. hosted requests above the default require an internal compile key.
+   */
+  buildBudgetMs?: number
 }) => Promise<SwiftCompileOutcome>
 
 /** the HTTP submitter, shared by the browser worker and the node build. */
@@ -285,10 +296,6 @@ export function httpSwiftCompileSubmit(
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 export function isSwiftNativeModules(value: unknown): value is SwiftNativeModules {
   return (
     isRecord(value) &&
@@ -394,6 +401,7 @@ export async function compileSwiftProject(
     images?: Record<string, SwiftImageUpload>
     entry: string
     packageId: string
+    buildBudgetMs?: number
   },
   origin: string,
   signal?: AbortSignal,

package/src/swift-toolchain.ts

@@ -1,4 +1,4 @@
-// the one place that finds the swift.org toolchain app Swift compiles with.
+// the one place that selects and verifies the toolchain app Swift compiles with.
 // a binary .swiftmodule loads only in the compiler release that wrote it, so
 // every caller names the release from packages/sootsim-swift/toolchain.json
 // or the Swift distribution's lock (docs/swift-distribution.md).
@@ -6,21 +6,72 @@
 // node builtins only: packages/sootsim-swift/scripts/build.sh imports this
 // file straight from a checkout, with no install.
 import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** swiftpm's SDK directory option, shared by discovery and compilation. */
+export function swiftSdkOptions(): string[] {
+  const directory = process.env.PEACH_SWIFT_SDKS_PATH
+  return directory ? ['--swift-sdks-path', path.resolve(directory)] : []
+}
+
+// host archives include the official driver/runtime and the qualified patched frontend.
+export const SWIFT_HOST_COMPILER_RELEASE = 'swift-6.4.0-RELEASE-custom-0d775d32d7c74eae'
+export const SWIFT_HOST_COMPILER_ID = '0d775d32d7c74eae'
+const compilerArchives: Record<string, { checksum: string; manifest: string }> = {
+  'darwin-arm64': {
+    checksum: '957e85486f92327ee5cf8d3c5bb9336d17ab80145c87645c637c49130a50477a',
+    manifest: 'c63e2f81694e8d8ad046d10c71d0638dbae4e5a36601294ed670988d1cb5b6f1',
+  },
+  'linux-x64': {
+    checksum: '6302230fb126b79c9af5fc2bc0208a936bb573c343da7ae949c5c1687e761cd2',
+    manifest: '31b507a6a8648a2266a187b9fed092e29a63cae99d57c5defdf2e82a7cbbc113',
+  },
+  'linux-arm64': {
+    checksum: '9b40d39ea5ba82fd9a417868f0a449f5e98e37cf83acaac9cedd3a8b8d91a218',
+    manifest: 'fe07a29d4f4374cad47b29de70e90aa2e3b7664e08c8b53d304585e65637da24',
+  },
+}
+
+export function swiftHostCompilerArchive(
+  release: string,
+  host = `${process.platform}-${process.arch}`,
+) {
+  if (release !== SWIFT_HOST_COMPILER_RELEASE)
+    throw new Error(`unqualified host compiler ${release}`)
+  const archive = compilerArchives[host]
+  if (!archive) throw new Error(`unsupported Swift compiler host ${host}`)
+  return {
+    ...archive,
+    identity: SWIFT_HOST_COMPILER_ID,
+    url: `https://r2.sootsim.com/swift-host-compiler/${SWIFT_HOST_COMPILER_ID}/${release}-${host}.tar.gz`,
+  }
+}
+
+// source archives and bootstrap images retain the official release name.
+export function swiftUpstreamRelease(release: string): string {
+  return release.replace(/-custom-[a-f0-9]{16}$/, '')
+}
 
 // swift.org's x.y.0 archives report the compiler identity as x.y.
 export function swiftCompilerRelease(release: string): string {
-  return release.replace(/^swift-(\d+\.\d+)\.0-RELEASE$/, 'swift-$1-RELEASE')
+  return swiftUpstreamRelease(release).replace(
+    /^swift-(\d+\.\d+)\.0-RELEASE$/,
+    'swift-$1-RELEASE',
+  )
 }
 
 /**
  * the bin directory of the toolchain for `release`, unverified. macOS: the
- * Xcode Toolchains directory, the user's before the system's. Linux: a
- * builder's `$CONTRAST_SWIFT_TOOLCHAINS/<release>`
+ * Xcode Toolchains directory, the user's before the system's. Linux:
+ * `$CONTRAST_SWIFT_TOOLCHAINS/<release>` when set
  * (packages/sootsim-swift/scripts/install-linux-toolchain.sh fills it), else
- * the cf-build image's `/opt/swift/<release>`, else the `swift` first on PATH.
+ * the cf-build image's `/opt/swift/<release>` when present, else a pinned
+ * compiler's user-writable `$PEACH_HOME/swift/toolchains/<release>`, else the
+ * `swift` first on PATH.
  */
 export function swiftToolchainBin(release: string): string {
   if (process.platform === 'darwin') {
@@ -34,6 +85,8 @@ export function swiftToolchainBin(release: string): string {
   }
   const image = path.join('/opt/swift', release, 'usr/bin')
   if (fs.existsSync(path.join(image, 'swift'))) return image
+  if (release.includes('-custom-'))
+    return path.join(peachHome(), 'swift', 'toolchains', release, 'usr/bin')
   return (
     (process.env.PATH ?? '')
       .split(path.delimiter)
@@ -41,6 +94,106 @@ export function swiftToolchainBin(release: string): string {
   )
 }
 
+// home-paths.ts's rnxHomeDir, repeated because this file imports node builtins only.
+function peachHome(): string {
+  const override = process.env.PEACH_HOME
+  return override ? path.resolve(override) : path.join(os.homedir(), '.peach')
+}
+
+let scratch: string | undefined
+let swiftHome: string | undefined
+/**
+ * keep the temporary files swift processes write (swiftpm's lock files and
+ * TemporaryDirectory folders, which it never removes) in a per-process
+ * directory under `root`, removed when this process exits, and on linux its
+ * home directory in `root/home`, kept so the caches persist. directories left
+ * by processes that no longer run are removed first. without this call swift
+ * inherits the caller's TMPDIR.
+ */
+export function confineSwiftScratch(root: string): void {
+  if (scratch) return
+  fs.mkdirSync(root, { recursive: true })
+  for (const name of fs.readdirSync(root)) {
+    const pid = Number(name)
+    if (Number.isInteger(pid) && pid > 0 && !processRuns(pid))
+      fs.rmSync(path.join(root, name), { recursive: true, force: true })
+  }
+  const dir = path.join(root, String(process.pid))
+  fs.mkdirSync(dir, { recursive: true })
+  scratch = dir
+  // swiftpm and clang write ~/.swiftpm and ~/.cache even with every path flag
+  // given; on linux no tool needs the real home, so they get a kept one here.
+  if (process.platform === 'linux') {
+    swiftHome = path.join(root, 'home')
+    fs.mkdirSync(swiftHome, { recursive: true })
+  }
+  // swiftpm makes ~/.swiftpm in the account's passwd home whatever HOME says;
+  // remove at exit only the entries swiftpm seeds there that were absent now:
+  // a cache link into a swiftpm cache folder and empty configuration and
+  // security folders. anything else, a link or file a user made included, stays.
+  const seeded = path.join(os.homedir(), '.swiftpm')
+  const dirAbsentBefore = lstatIfKnown(seeded) === null
+  const absentBefore = swiftpmSeeds.filter(
+    (name) => lstatIfKnown(path.join(seeded, name)) === null,
+  )
+  process.once('exit', () => {
+    fs.rmSync(dir, { recursive: true, force: true })
+    for (const name of absentBefore) removeSwiftpmSeed(path.join(seeded, name), name)
+    if (dirAbsentBefore && lstatIfKnown(seeded)?.isDirectory())
+      try {
+        fs.rmdirSync(seeded)
+      } catch {}
+  })
+}
+
+const swiftpmSeeds = ['cache', 'configuration', 'security']
+
+// only a missing path establishes absence; other lookup failures stay unknown.
+function lstatIfKnown(entry: string): fs.Stats | null | undefined {
+  try {
+    return fs.lstatSync(entry)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return null
+    return undefined
+  }
+}
+
+function removeSwiftpmSeed(entry: string, name: string): void {
+  const stat = lstatIfKnown(entry)
+  if (!stat) return
+  try {
+    if (name === 'cache') {
+      if (
+        stat.isSymbolicLink() &&
+        fs.readlinkSync(entry).endsWith('/.cache/org.swift.swiftpm')
+      )
+        fs.unlinkSync(entry)
+    } else if (stat.isDirectory()) {
+      fs.rmdirSync(entry)
+    }
+  } catch {}
+}
+
+function processRuns(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error instanceof Error && 'code' in error && error.code === 'EPERM'
+  }
+}
+
+/** the environment every swift process runs with: `base`, with TMPDIR in the
+ *  confined scratch directory when the caller set one. */
+export function swiftEnvironment(
+  base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  if (!scratch) return base
+  return swiftHome
+    ? { ...base, TMPDIR: scratch, HOME: swiftHome }
+    : { ...base, TMPDIR: scratch }
+}
+
 /** the wasm SDK a release compiles with: its installed id, where it
  *  downloads from and its archive checksum (packages/sootsim-swift/toolchain.json). */
 export interface SwiftWasmSdk {
@@ -49,67 +202,372 @@ export interface SwiftWasmSdk {
   wasmSdkChecksum: string
 }
 
-const verified = new Map<string, string>()
-
 /**
  * swiftToolchainBin, checked: its swift is exactly `release` and has the
  * pinned wasm SDK installed. anything else fails with one message naming the
  * release and the commands that install it.
  */
 export function swiftToolchain(release: string, sdk: SwiftWasmSdk): string {
-  const cached = verified.get(`${release}\0${sdk.wasmSdkId}`)
-  if (cached) return cached
-  const bin = swiftToolchainBin(release)
-  const swift = path.join(bin, 'swift')
-  const version = fs.existsSync(swift)
-    ? execFileSync(swift, ['--version'], {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-    : ''
-  if (!version.includes(`(${swiftCompilerRelease(release)})`)) {
-    const found = version
-      ? `found ${version.split('\n')[0]?.trim()} at ${swift}`
-      : process.platform === 'darwin'
-        ? `found no ${release}.xctoolchain in ~/Library/Developer/Toolchains or /Library/Developer/Toolchains`
-        : 'found no swift on PATH'
+  validateSwiftSdkIdentity(sdk)
+  let bin: string
+  try {
+    bin = swiftCompiler(release)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
     throw new Error(
-      `peach compiles Swift with the swift.org toolchain ${release} and its wasm SDK; ${found}.\n${swiftInstallSteps(release, sdk)}`,
+      `Swift compiler ${release} is unavailable or differs from its pin: ${reason}\n${swiftInstallSteps(release, sdk)}`,
     )
   }
-  const sdks = execFileSync(swift, ['sdk', 'list'], {
+  const swift = path.join(bin, 'swift')
+  const sdks = execFileSync(swift, ['sdk', 'list', ...swiftSdkOptions()], {
     encoding: 'utf8',
+    env: swiftEnvironment(),
     stdio: ['ignore', 'pipe', 'pipe'],
   })
   if (!sdks.split('\n').some((line) => line.trim() === sdk.wasmSdkId)) {
     throw new Error(
-      `peach compiles Swift with the ${sdk.wasmSdkId} SDK, which ${swift} does not have.\n${swiftInstallSteps(release, sdk)}`,
+      `peach compiles Swift with the ${sdk.wasmSdkId} SDK, which ${swift} does not have.\n${swiftSdkInstallStep(release, sdk)}`,
+    )
+  }
+  try {
+    verifySwiftSdk(swift, sdk)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`${reason}\n${swiftSdkInstallStep(release, sdk)}`)
+  }
+  return bin
+}
+
+// swiftpm's info.json describes SDK selection, not the archive it came from.
+function validateSwiftSdkIdentity(sdk: SwiftWasmSdk): void {
+  if (
+    !/^[a-zA-Z0-9._-]+$/.test(sdk.wasmSdkId) ||
+    !/^[a-f0-9]{64}$/.test(sdk.wasmSdkChecksum)
+  )
+    throw new Error('invalid Swift SDK identity or checksum')
+}
+
+function swiftSdkBundle(swift: string, id: string, options: string[]): string {
+  const configuration = execFileSync(
+    swift,
+    ['sdk', 'configure', ...options, '--show-configuration', id, 'wasm32-unknown-wasip1'],
+    { encoding: 'utf8', env: swiftEnvironment(), stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const sysroot = /^sdkRootPath: (.+)$/m.exec(configuration)?.[1]?.trim()
+  if (!sysroot || !path.isAbsolute(sysroot))
+    throw new Error(`Swift SDK ${id} reports no absolute sdkRootPath`)
+  let bundle = sysroot
+  while (!bundle.endsWith('.artifactbundle')) {
+    const parent = path.dirname(bundle)
+    if (parent === bundle)
+      throw new Error(`Swift SDK ${id} is outside an artifact bundle`)
+    bundle = parent
+  }
+  return fs.realpathSync(bundle)
+}
+
+// stat changes invalidate file hashes; every lookup enumerates the entire bundle,
+// including additions, removals, executable modes and internal symlink targets.
+const sdkFileHashes = new Map<string, { stamp: string; checksum: string }>()
+function swiftSdkPayloadChecksum(bundle: string): string {
+  const hash = createHash('sha256')
+  function visit(relative: string): void {
+    const file = path.join(bundle, relative)
+    const stat = fs.lstatSync(file, { bigint: true })
+    if (stat.isSymbolicLink()) {
+      const resolved = path.relative(bundle, fs.realpathSync(file))
+      if (
+        resolved === '..' ||
+        resolved.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(resolved)
+      )
+        throw new Error(`Swift SDK symlink escapes its bundle: ${relative}`)
+      hash.update(JSON.stringify([relative, 'link', fs.readlinkSync(file)]) + '\n')
+    } else if (stat.isDirectory()) {
+      hash.update(JSON.stringify([relative, 'directory']) + '\n')
+      for (const name of fs.readdirSync(file).sort()) visit(path.join(relative, name))
+    } else if (stat.isFile()) {
+      const stamp = [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':')
+      let cached = sdkFileHashes.get(file)
+      if (cached?.stamp !== stamp) {
+        cached = { stamp, checksum: swiftFileChecksum(file) }
+        sdkFileHashes.set(file, cached)
+      }
+      hash.update(
+        JSON.stringify([relative, 'file', Number(stat.mode & 0o111n), cached.checksum]) +
+          '\n',
+      )
+    } else throw new Error(`unsupported Swift SDK payload entry: ${relative}`)
+  }
+  visit('')
+  return hash.digest('hex')
+}
+
+function swiftSdkVerificationFile(bundle: string, sdk: SwiftWasmSdk): string {
+  return path.join(
+    path.dirname(bundle),
+    '.peach-sdk-checksums',
+    `${sdk.wasmSdkId}-${sdk.wasmSdkChecksum}.json`,
+  )
+}
+
+function verifySwiftSdk(swift: string, sdk: SwiftWasmSdk): void {
+  const bundle = swiftSdkBundle(swift, sdk.wasmSdkId, swiftSdkOptions())
+  const file = swiftSdkVerificationFile(bundle, sdk)
+  if (!fs.existsSync(file))
+    throw new Error(
+      `Swift SDK ${sdk.wasmSdkId} has no verified archive binding for ${sdk.wasmSdkChecksum}. Hydrate it with installSwiftWasmSdk before compiling.`,
     )
+  const receipt: unknown = JSON.parse(fs.readFileSync(file, 'utf8'))
+  if (
+    !receipt ||
+    typeof receipt !== 'object' ||
+    !('wasmSdkId' in receipt) ||
+    receipt.wasmSdkId !== sdk.wasmSdkId ||
+    !('wasmSdkChecksum' in receipt) ||
+    receipt.wasmSdkChecksum !== sdk.wasmSdkChecksum ||
+    !('payloadChecksum' in receipt) ||
+    receipt.payloadChecksum !== swiftSdkPayloadChecksum(bundle)
+  )
+    throw new Error(
+      `Swift SDK ${sdk.wasmSdkId} installed payload differs from its verified archive ${sdk.wasmSdkChecksum}`,
+    )
+}
+
+/** install or qualify existing bytes, serializing shared-store mutation without replacement. */
+function installSwiftSdkArchive(swift: string, sdk: SwiftWasmSdk, archive: string): void {
+  validateSwiftSdkIdentity(sdk)
+  const staging = fs.realpathSync(
+    fs.mkdtempSync(path.join(scratch ?? os.tmpdir(), 'peach-sdk-verification-')),
+  )
+  try {
+    if (swiftFileChecksum(archive) !== sdk.wasmSdkChecksum)
+      throw new Error('declared Swift SDK archive checksum mismatch')
+    const store = path.join(staging, 'sdks')
+    fs.mkdirSync(store)
+    execFileSync(
+      swift,
+      [
+        'sdk',
+        'install',
+        archive,
+        '--checksum',
+        sdk.wasmSdkChecksum,
+        '--swift-sdks-path',
+        store,
+      ],
+      { env: swiftEnvironment(), stdio: 'inherit' },
+    )
+    const stagedBundle = swiftSdkBundle(swift, sdk.wasmSdkId, [
+      '--swift-sdks-path',
+      store,
+    ])
+    const expected = swiftSdkPayloadChecksum(stagedBundle)
+    const directory = process.env.PEACH_SWIFT_SDKS_PATH
+    const locks = directory
+      ? path.join(path.resolve(directory), '.peach-locks')
+      : path.join(os.homedir(), '.swiftpm', 'builder-locks')
+    fs.mkdirSync(locks, { recursive: true })
+    execFileSync(
+      'perl',
+      [
+        '-e',
+        'use Fcntl qw(:flock); my ($lock, $id, $bundle, $swift, @options) = @ARGV; open(my $fd, ">>", $lock) or die $!; flock($fd, LOCK_EX) or die $!; open(my $list, "-|", $swift, "sdk", "list", @options) or die $!; my $found = 0; while (<$list>) { s/^\\s+|\\s+$//g; $found = 1 if $_ eq $id; } close($list) or die "swift sdk list failed"; unless ($found) { system($swift, "sdk", "install", $bundle, @options); exit(($? & 127) ? 128 + ($? & 127) : $? >> 8); }',
+        path.join(locks, 'wasm-sdk.lock'),
+        sdk.wasmSdkId,
+        stagedBundle,
+        swift,
+        ...swiftSdkOptions(),
+      ],
+      { env: swiftEnvironment(), stdio: 'inherit' },
+    )
+    const bundle = swiftSdkBundle(swift, sdk.wasmSdkId, swiftSdkOptions())
+    if (swiftSdkPayloadChecksum(bundle) !== expected)
+      throw new Error(
+        `Swift SDK ${sdk.wasmSdkId} already exists with different payload bytes; select a separate --swift-sdks-path. No installed SDK was replaced.`,
+      )
+    const file = swiftSdkVerificationFile(bundle, sdk)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const temporary = `${file}.${process.pid}.tmp`
+    try {
+      fs.writeFileSync(
+        temporary,
+        JSON.stringify({
+          wasmSdkId: sdk.wasmSdkId,
+          wasmSdkChecksum: sdk.wasmSdkChecksum,
+          payloadChecksum: expected,
+        }) + '\n',
+      )
+      fs.renameSync(temporary, file)
+    } finally {
+      fs.rmSync(temporary, { force: true })
+    }
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true })
+    for (const file of sdkFileHashes.keys())
+      if (file.startsWith(staging + path.sep)) sdkFileHashes.delete(file)
+  }
+}
+
+/** verify the compiler and install a declared SDK under the shared store lock. */
+export function installSwiftWasmSdk(release: string, sdk: SwiftWasmSdk): void {
+  validateSwiftSdkIdentity(sdk)
+  try {
+    swiftToolchain(release, sdk)
+    return
+  } catch {
+    // an unverified existing SDK must be compared with the declared archive.
+  }
+  const swift = path.join(swiftCompiler(release), 'swift')
+  const staging = fs.mkdtempSync(path.join(scratch ?? os.tmpdir(), 'builder-swift-sdk-'))
+  const archive = path.join(staging, 'sdk.artifactbundle.tar.gz')
+  try {
+    if (sdk.wasmSdkUrl.startsWith('file:'))
+      fs.copyFileSync(fileURLToPath(sdk.wasmSdkUrl), archive)
+    else
+      execFileSync('curl', ['-fsSL', sdk.wasmSdkUrl, '-o', archive], { stdio: 'inherit' })
+    installSwiftSdkArchive(swift, sdk, archive)
+    swiftToolchain(release, sdk)
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true })
+  }
+}
+
+// stream large compiler binaries without retaining a second copy in memory.
+export function swiftFileChecksum(file: string): string {
+  const hash = createHash('sha256')
+  const fd = fs.openSync(file, 'r')
+  const buffer = Buffer.allocUnsafe(1024 * 1024)
+  try {
+    let size = fs.readSync(fd, buffer, 0, buffer.length, null)
+    while (size > 0) {
+      hash.update(buffer.subarray(0, size))
+      size = fs.readSync(fd, buffer, 0, buffer.length, null)
+    }
+  } finally {
+    fs.closeSync(fd)
+  }
+  return hash.digest('hex')
+}
+
+/** validate the pinned manifest and every replaced binary, independently of --version. */
+export function verifySwiftHostCompiler(release: string, root: string): void {
+  const pin = swiftHostCompilerArchive(release)
+  const file = path.join(root, 'compiler.json')
+  if (swiftFileChecksum(file) !== pin.manifest)
+    throw new Error(`Swift compiler manifest mismatch at ${root}`)
+  const manifest: unknown = JSON.parse(fs.readFileSync(file, 'utf8'))
+  if (
+    !manifest ||
+    typeof manifest !== 'object' ||
+    !('identity' in manifest) ||
+    manifest.identity !== pin.identity ||
+    !('host' in manifest) ||
+    manifest.host !== `${process.platform}-${process.arch}` ||
+    !('files' in manifest) ||
+    !manifest.files ||
+    typeof manifest.files !== 'object'
+  ) {
+    throw new Error(`Swift compiler identity mismatch at ${root}`)
   }
-  verified.set(`${release}\0${sdk.wasmSdkId}`, bin)
+  const files = Object.entries(manifest.files)
+  if (files.length !== 16) throw new Error('incomplete Swift compiler manifest')
+  for (const [relative, checksum] of files) {
+    if (
+      relative.startsWith('/') ||
+      relative.split('/').includes('..') ||
+      typeof checksum !== 'string' ||
+      swiftFileChecksum(path.join(root, relative)) !== checksum
+    ) {
+      throw new Error(`Swift compiler binary mismatch: ${relative}`)
+    }
+  }
+}
+
+const verifiedCompilers = new Map<string, string>()
+/** select the actual compiler, including its patched identity, before consulting SDKs. */
+export function swiftCompiler(release: string): string {
+  const cached = verifiedCompilers.get(release)
+  if (cached) return cached
+  const bin = swiftToolchainBin(release)
+  if (release.includes('-custom-'))
+    verifySwiftHostCompiler(release, path.resolve(bin, '../..'))
+  const version = execFileSync(path.join(bin, 'swift'), ['--version'], {
+    encoding: 'utf8',
+    env: swiftEnvironment(),
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (!version.includes(`(${swiftCompilerRelease(release)})`))
+    throw new Error(`compiler release mismatch at ${bin}`)
+  verifiedCompilers.set(release, bin)
   return bin
 }
 
-/** the commands that install `release` and its wasm SDK on this host. */
+/** the command that installs and qualifies the pinned SDK for an installed compiler. */
+export function swiftSdkInstallStep(release: string, wasmSdk: SwiftWasmSdk): string {
+  return `install the pinned SDK:\n  ${swiftSdkInstallCommand(release, wasmSdk)}`
+}
+
+function swiftSdkInstallCommand(release: string, wasmSdk: SwiftWasmSdk): string {
+  const { wasmSdkId, wasmSdkUrl, wasmSdkChecksum } = wasmSdk
+  const program = `import { installSwiftWasmSdk } from "peachsim/swift-toolchain"; installSwiftWasmSdk(${JSON.stringify(release)}, ${JSON.stringify({ wasmSdkId, wasmSdkUrl, wasmSdkChecksum })})`
+  const directory = process.env.PEACH_SWIFT_SDKS_PATH
+  const environment = directory
+    ? `PEACH_SWIFT_SDKS_PATH='${path.resolve(directory).replaceAll("'", "'\\''")}' `
+    : ''
+  return `${environment}node --input-type=module -e '${program.replaceAll("'", "'\\''")}'`
+}
+
+/** the commands that install the pinned compiler and SDK on this host. */
 export function swiftInstallSteps(release: string, wasmSdk: SwiftWasmSdk): string {
+  const { note, commands } = swiftCompilerInstall(release)
+  return [
+    `install the pinned compiler and SDK${note}:`,
+    ...[...commands, swiftSdkInstallCommand(release, wasmSdk)].map((line) => `  ${line}`),
+  ].join('\n')
+}
+
+/** the commands that install the pinned compiler alone, for a caller that installs the SDK. */
+export function swiftCompilerInstallSteps(release: string): string {
+  const { note, commands } = swiftCompilerInstall(release)
+  return [
+    `install the pinned compiler${note}:`,
+    ...commands.map((line) => `  ${line}`),
+  ].join('\n')
+}
+
+function swiftCompilerInstall(release: string): { note: string; commands: string[] } {
+  if (release.includes('-custom-')) {
+    const archive = swiftHostCompilerArchive(release)
+    const directory = path.resolve(swiftToolchainBin(release), '../..')
+    return {
+      note: '',
+      commands: [
+        `curl -fsSL ${archive.url} -o compiler.tar.gz`,
+        `echo '${archive.checksum}  compiler.tar.gz' | shasum -a 256 -c -`,
+        `mkdir -p '${directory}'`,
+        `tar -xzf compiler.tar.gz --strip-components=1 -C '${directory}'`,
+      ],
+    }
+  }
   const version = release.replace(/^swift-/, '').toLowerCase()
   const downloads = `https://download.swift.org/swift-${version}`
-  const sdk = `swift sdk install ${wasmSdk.wasmSdkUrl} --checksum ${wasmSdk.wasmSdkChecksum}`
   if (process.platform === 'darwin') {
-    const swift = `~/Library/Developer/Toolchains/${release}.xctoolchain/usr/bin/swift`
-    return [
-      'install it:',
-      `  curl -fsSLO ${downloads}/xcode/${release}/${release}-osx.pkg`,
-      `  installer -pkg ${release}-osx.pkg -target CurrentUserHomeDirectory`,
-      `  ${swift} ${sdk.replace(/^swift /, '')}`,
-    ].join('\n')
+    return {
+      note: '',
+      commands: [
+        `curl -fsSLO ${downloads}/xcode/${release}/${release}-osx.pkg`,
+        `installer -pkg ${release}-osx.pkg -target CurrentUserHomeDirectory`,
+      ],
+    }
   }
   const platform = `debian12${process.arch === 'arm64' ? '-aarch64' : ''}`
   const name = `${release}-${platform}`
-  return [
-    'install it (Debian 12 shown; other distributions: https://www.swift.org/install/linux/):',
-    `  curl -fsSL ${downloads}/${platform}/${release}/${name}.tar.gz | tar -xz -C /opt`,
-    `  export PATH=/opt/${name}/usr/bin:$PATH`,
-    `  ${sdk}`,
-  ].join('\n')
+  return {
+    note: ' (Debian 12 shown; other distributions: https://www.swift.org/install/linux/)',
+    commands: [
+      `curl -fsSL ${downloads}/${platform}/${release}/${name}.tar.gz | tar -xz -C /opt`,
+      `export PATH=/opt/${name}/usr/bin:$PATH`,
+    ],
+  }
 }