peachsim 0.1.1620 → 0.1.1635

package/src/swift-standins.ts

@@ -12,9 +12,9 @@
 import { execFileSync, spawnSync } 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 { getCliVersion } from './cli-version'
+import { cacheDir as peachCacheDir, swiftPackageCacheOptions } from './home-paths'
 import { parsePlistSource } from './plist'
 import {
   swiftDistributionAt,
@@ -24,7 +24,7 @@ import {
   swiftPeachModules,
   swiftSdkPaths,
 } from './swift-compile'
-import { IOS_SDK_ID, objcView } from './swift-objc-standin'
+import { IOS_SDK_ID, objcView, type ObjcSurface } from './swift-objc-standin'
 import {
   STANDIN_EMIT_VERSION,
   STANDIN_IMPORTS,
@@ -33,11 +33,14 @@ import {
   type SwiftStandinBehaviors,
   type StandinBehavior,
 } from './swift-standin-emit'
+import { swiftSdkOptions } from './swift-toolchain'
 import type { SwiftPackageBinary } from './swift-packages'
 
 const TRIPLE = 'wasm32-unknown-wasip1'
-// builder workspaces share this persistent cache; temporary directories hold only work.
-const cacheDir = path.join(os.homedir(), 'builders/cache/peach-swift-standins')
+// every stand-in artifact and temporary workspace belongs to peach.
+const cacheDir = path.join(peachCacheDir(), 'swift-standins')
+// each binary stand-in is a target under its module's directory here.
+export const SWIFT_STANDINS_DIR = '__standins__'
 
 export interface SwiftStandin {
   /** the module it stands in for, which names its compile target. */
@@ -46,6 +49,8 @@ export interface SwiftStandin {
   target: string
   /** the target's files, relative to its directory. */
   files: Record<string, string>
+  /** other generated modules named by this target's public headers. */
+  dependencies?: string[]
 }
 
 export interface SwiftStandins {
@@ -59,6 +64,8 @@ interface Toolchain {
   toolchainBin: string
   /** the toolchain release, read once where the toolchain is resolved. */
   release: string
+  /** modules generated earlier in this dependency closure. */
+  standinModules?: string
 }
 
 function exec(file: string, args: string[], cwd?: string): string {
@@ -216,7 +223,7 @@ const files = (dir: string, test: (name: string) => boolean): string[] =>
 type Surface =
   | { kind: 'swift'; module: string; interface: string }
   | { kind: 'c'; module: string; modulemap: string; headers: string }
-  | { kind: 'objc'; module: string; modulemap: string; headers: string }
+  | (ObjcSurface & { kind: 'objc' })
 
 const OBJC = /^\s*(?:@interface|@protocol|@class|@import|#import)\b/m
 
@@ -303,10 +310,12 @@ function peachModuleDirs(toolchain: Toolchain, imports: string[]): string[] {
       path.join(toolchainBin, 'swift'),
       [
         'build',
+        ...swiftPackageCacheOptions(),
         '--build-system',
         'native',
         '-j',
         '4',
+        ...swiftSdkOptions(),
         '--swift-sdk',
         swiftModuleSdk(moduleRoot).wasmSdkId,
         '-c',
@@ -432,7 +441,13 @@ function wasmFlags(toolchain: Toolchain, imports: string[]): string[] {
     sysroot,
     '-resource-dir',
     resources,
+    // the sdk toolset's emulation defines, which raw swiftc does not read
+    '-Xcc',
+    '-D_WASI_EMULATED_SIGNAL',
+    '-Xcc',
+    '-D_WASI_EMULATED_MMAN',
     ...peachModuleDirs(toolchain, imports).flatMap((dir) => ['-I', dir]),
+    ...(toolchain.standinModules ? ['-I', toolchain.standinModules] : []),
   ]
 }
 
@@ -460,6 +475,7 @@ function objcStandin(
     toolchain,
     work,
     behavior,
+    binary.headerDependencies?.map((dependency) => dependency.module),
   )
 }
 
@@ -475,6 +491,7 @@ function graphStandin(
   toolchain: Toolchain,
   work: string,
   behavior: ReadonlyMap<string, StandinBehavior>,
+  imports: string[] = [],
 ): SwiftStandin {
   const paths = new Set(
     graphs.flatMap((graph) =>
@@ -498,6 +515,9 @@ function graphStandin(
       behavior,
       omit,
       plain,
+      inert: binary.publicHeaders !== undefined,
+      imports,
+      family: imports,
     })
     for (const entry of skipped) {
       if (behavior.has(entry.path))
@@ -525,6 +545,7 @@ function graphStandin(
         module,
         target: binary.target,
         files: { [`${module}.swift`]: source },
+        ...(imports.length ? { dependencies: imports } : {}),
       }
     const before = omit.size + plain.size
     const elsewhere: string[] = []
@@ -899,6 +920,7 @@ export function standinLibrary(
   binary: SwiftPackageBinary,
   searchRoot: string,
 ): string | null {
+  if (binary.publicHeaders !== undefined) return null
   const dir = xcframework(binary).dir
   const library = simulatorLibraryName(dir)
   const supplied = path.join(dir, RUST_TARGET)
@@ -920,14 +942,18 @@ export function standinLibrary(
     [
       'build',
       '--release',
+      '--locked',
       '--target',
       RUST_TARGET,
       '--message-format=json-render-diagnostics',
       '--manifest-path',
       manifest,
+      '--target-dir',
+      path.join(cacheDir, 'cargo', key(manifest)),
     ],
     {
       encoding: 'utf8',
+      env: { ...process.env, CARGO_HOME: path.join(cacheDir, 'cargo-home') },
       maxBuffer: 256 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'pipe'],
     },
@@ -976,10 +1002,31 @@ function sourceBinaryStandins(
   behavior: SwiftStandinBehaviors,
 ): SwiftStandin[] | string {
   const repo = path.resolve(toolchain.moduleRoot, '../..')
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'peach-standin-request-'))
+  fs.mkdirSync(cacheDir, { recursive: true })
+  const work = fs.mkdtempSync(path.join(cacheDir, 'request-'))
   try {
-    const artifact = xcframework(binary)
+    const artifact =
+      binary.publicHeaders !== undefined
+        ? { dir: path.join(work, 'headers') }
+        : xcframework(binary)
     const local = { ...binary, dir: artifact.dir, url: null, checksum: null }
+    if (binary.publicHeaders !== undefined) {
+      const dependencies = binary.headerDependencies ?? []
+      for (const header of [
+        { module: binary.target, path: binary.publicHeaders },
+        ...dependencies,
+      ])
+        fs.cpSync(
+          path.join(binary.dir, header.path),
+          path.join(artifact.dir, header.module),
+          { recursive: true },
+        )
+      local.publicHeaders = binary.target
+      local.headerDependencies = dependencies.map(({ module }) => ({
+        module,
+        path: module,
+      }))
+    }
     const generation = standinGenerationInputs([local], toolchain, behavior)
     const request = path.join(work, 'request.json')
     const delivery = path.join(work, 'delivery')
@@ -993,7 +1040,7 @@ function sourceBinaryStandins(
         release: toolchain.release,
       }),
     )
-    execFileSync(
+    const build = spawnSync(
       'bun',
       [
         path.join(repo, 'scripts/build/swift-standins-submit.ts'),
@@ -1004,11 +1051,20 @@ function sourceBinaryStandins(
         '--delivery-dir',
         delivery,
       ],
-      { cwd: repo, stdio: 'inherit' },
-    )
-    const receipt: unknown = JSON.parse(
-      fs.readFileSync(path.join(delivery, 'standins.json'), 'utf8'),
+      { cwd: repo, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
     )
+    if (build.stdout) process.stdout.write(build.stdout)
+    if (build.stderr) process.stderr.write(build.stderr)
+    if (build.error || build.status !== 0)
+      throw new Error(
+        `source stand-in build for ${binary.target} failed (${build.error?.message ?? build.signal ?? `exit ${build.status}`}): ${build.stderr?.trim().slice(-4000) || build.stdout?.trim().slice(-4000) || 'builder returned no diagnostic'}`,
+      )
+    const output = path.join(delivery, 'standins.json')
+    if (!fs.existsSync(output))
+      throw new Error(
+        `source stand-in builder returned no standins.json for ${binary.target}`,
+      )
+    const receipt: unknown = JSON.parse(fs.readFileSync(output, 'utf8'))
     if (
       !receipt ||
       typeof receipt !== 'object' ||
@@ -1055,7 +1111,7 @@ export function standinGenerationInputs(
   const { moduleRoot, release } = toolchain
   const sdk = swiftModuleSdk(moduleRoot)
   const parts = [
-    'standin/v4',
+    'standin/v6',
     release,
     sdk.wasmSdkId,
     sdk.wasmSdkChecksum,
@@ -1068,7 +1124,9 @@ export function standinGenerationInputs(
   const modules = new Set(
     binaries.flatMap((binary) => {
       try {
-        return surfaces(xcframework(binary).dir).map((surface) => surface.module)
+        return binary.publicHeaders !== undefined
+          ? [binary.target]
+          : surfaces(xcframework(binary).dir).map((surface) => surface.module)
       } catch {
         return []
       }
@@ -1095,7 +1153,15 @@ export function standinGenerationInputs(
         binary.source,
         binary.url ?? '',
         binary.checksum ?? '',
-        xcframework(binary).digest,
+        binary.publicHeaders !== undefined
+          ? [
+              treeDigest(path.join(binary.dir, binary.publicHeaders)),
+              ...(binary.headerDependencies ?? []).map(
+                (dependency) =>
+                  `${dependency.module}\0${treeDigest(path.join(binary.dir, dependency.path))}`,
+              ),
+            ].join('\0')
+          : xcframework(binary).digest,
       )
     } catch {
       // unreadable here fails again below, where it becomes a gap
@@ -1128,17 +1194,55 @@ function binaryStandins(
   // calls, so peach names the path and asks for the artifact
   if (!binary.url && !fs.existsSync(binary.dir))
     return `${path.relative(process.cwd(), binary.dir) || binary.dir} is not on disk, and Xcode fails without it too; run the script that downloads or builds it, then run again`
+  fs.mkdirSync(cacheDir, { recursive: true })
+  const work = fs.mkdtempSync(path.join(cacheDir, 'work-'))
   let all: Surface[]
   let digest: string
   try {
-    const artifact = xcframework(binary)
-    all = surfaces(artifact.dir)
-    digest = artifact.digest
+    if (binary.publicHeaders !== undefined) {
+      const headers = path.join(binary.dir, binary.publicHeaders)
+      const modulemap = path.join(work, 'module.modulemap')
+      const supplied = path.join(headers, 'module.modulemap')
+      const roots = files(headers, (name) => name.endsWith('.h'))
+      if (roots.length === 0)
+        throw new Error('its public header directory has no headers')
+      fs.writeFileSync(
+        modulemap,
+        fs.existsSync(supplied)
+          ? fs.readFileSync(supplied, 'utf8')
+          : `module ${binary.target} {\n${roots.map((file) => `  header "${file}"`).join('\n')}\n  export *\n}\n`,
+      )
+      all = [
+        {
+          kind: 'objc',
+          module: binary.target,
+          modulemap,
+          headers,
+          dependencies: binary.headerDependencies?.map((dependency) => ({
+            module: dependency.module,
+            headers: path.join(binary.dir, dependency.path),
+          })),
+        },
+      ]
+      digest = [
+        treeDigest(headers),
+        ...(binary.headerDependencies ?? []).map(
+          (dependency) =>
+            `${dependency.module}\0${treeDigest(path.join(binary.dir, dependency.path))}`,
+        ),
+      ].join('\0')
+    } else {
+      const artifact = xcframework(binary)
+      all = surfaces(artifact.dir)
+      digest = artifact.digest
+    }
   } catch (error) {
+    fs.rmSync(work, { recursive: true, force: true })
     return error instanceof Error ? error.message : String(error)
   }
   const found = all.filter((surface) => !provided.has(surface.module))
   if (found.length === 0) {
+    fs.rmSync(work, { recursive: true, force: true })
     if (all.length > 0) return []
     return 'its iOS simulator slice has no Swift interface or C modulemap'
   }
@@ -1162,18 +1266,22 @@ function binaryStandins(
   }
   const id = hash.digest('hex').slice(0, 32)
   const memo = built.get(id)
-  if (memo) return memo
+  if (memo) {
+    fs.rmSync(work, { recursive: true, force: true })
+    return memo
+  }
   const cached = path.join(cacheDir, 'standins', `${id}.json`)
   if (fs.existsSync(cached)) {
     const value: SwiftStandin[] = JSON.parse(fs.readFileSync(cached, 'utf8'))
     built.set(id, value)
+    fs.rmSync(work, { recursive: true, force: true })
     return value
   }
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'peach-standin-'))
   let result: SwiftStandin[] | string
   try {
     result =
       process.platform === 'darwin' &&
+      process.env.TM_EXEC_BUILD_PLATFORM !== 'mac' &&
       process.env.TM_SESSION &&
       process.env.CI !== 'true' &&
       toolchain.moduleRoot === path.resolve(import.meta.dirname, '../../sootsim-swift') &&
@@ -1246,10 +1354,62 @@ export function swiftStandins(
 ): SwiftStandins {
   const standins: SwiftStandin[] = []
   const gaps = new Map<string, string>()
-  for (const binary of binaries) {
-    const result = binaryStandins(binary, toolchain, provided, behavior)
-    if (typeof result === 'string') gaps.set(binary.target, result)
-    else standins.push(...result)
+  fs.mkdirSync(cacheDir, { recursive: true })
+  const modules = fs.mkdtempSync(path.join(cacheDir, 'modules-'))
+  const generatedToolchain = { ...toolchain, standinModules: modules }
+  const byTarget = new Map(binaries.map((binary) => [binary.target, binary]))
+  const prerequisites = new Set(
+    binaries.flatMap((binary) =>
+      (binary.headerDependencies ?? []).map((dependency) => dependency.module),
+    ),
+  )
+  const visited = new Set<string>()
+  const visit = (binary: SwiftPackageBinary) => {
+    if (visited.has(binary.target)) return
+    visited.add(binary.target)
+    for (const dependency of binary.headerDependencies ?? []) {
+      const target = byTarget.get(dependency.module)
+      if (target) visit(target)
+    }
+    const result = binaryStandins(binary, generatedToolchain, provided, behavior)
+    if (typeof result === 'string') {
+      gaps.set(binary.target, result)
+      return
+    }
+    for (const standin of result) {
+      // source objc dependents typecheck against the same generated declarations
+      // that the app links, including on cache hits.
+      if (prerequisites.has(standin.module)) {
+        const source = standin.files[`${standin.module}.swift`]
+        if (source !== undefined) {
+          const file = path.join(modules, `${standin.module}.swift`)
+          fs.writeFileSync(file, source)
+          try {
+            exec(path.join(toolchain.toolchainBin, 'swiftc'), [
+              '-emit-module',
+              '-parse-as-library',
+              '-swift-version',
+              '5',
+              '-module-name',
+              standin.module,
+              ...wasmFlags(generatedToolchain, standin.dependencies ?? []),
+              '-emit-module-path',
+              path.join(modules, `${standin.module}.swiftmodule`),
+              file,
+            ])
+          } catch (error) {
+            gaps.set(binary.target, failure(error))
+            return
+          }
+        }
+      }
+      standins.push(standin)
+    }
+  }
+  try {
+    for (const binary of binaries) visit(binary)
+    return { standins, gaps }
+  } finally {
+    fs.rmSync(modules, { recursive: true, force: true })
   }
-  return { standins, gaps }
 }

package/src/swift-submit.ts

@@ -32,6 +32,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
@@ -237,6 +241,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. */
@@ -394,6 +403,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,13 +6,61 @@
 // 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'
 
+/** 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-91504a66b3f012ac'
+export const SWIFT_HOST_COMPILER_ID = '91504a66b3f012ac'
+const compilerArchives: Record<string, { checksum: string; manifest: string }> = {
+  'darwin-arm64': {
+    checksum: '5d0ecbafd88c896beac74fd74c9d5fb20f973e0f58abbc1d2f27d5af0cbc4e59',
+    manifest: '827130a60b782ed413c9df41410afe7baf32dcb132b945a70ac0ff4c0594c690',
+  },
+  'linux-x64': {
+    checksum: '9d8491107efa347ccadf5f6974e80b2cff2b33cd8c34317dab777c5542512b3e',
+    manifest: '6221c024fa86b2201dcada23d9e13f6a11d7450cf22164a9708703f992de129f',
+  },
+  'linux-arm64': {
+    checksum: '14f5c7b39b1e36a1d9ce426a875676182fdb5247763a7e99cb72f74957bc0d9a',
+    manifest: '57ff31b79f9b3d9a6c0fd51c73271cdd88088522c0fc6d7a28ade03d68008b68',
+  },
+}
+
+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',
+  )
 }
 
 /**
@@ -33,7 +81,8 @@ export function swiftToolchainBin(release: string): string {
     return path.join(process.env.CONTRAST_SWIFT_TOOLCHAINS, release, 'usr/bin')
   }
   const image = path.join('/opt/swift', release, 'usr/bin')
-  if (fs.existsSync(path.join(image, 'swift'))) return image
+  if (release.includes('-custom-') || fs.existsSync(path.join(image, 'swift')))
+    return image
   return (
     (process.env.PATH ?? '')
       .split(path.delimiter)
@@ -57,27 +106,20 @@ const verified = new Map<string, string>()
  * release and the commands that install it.
  */
 export function swiftToolchain(release: string, sdk: SwiftWasmSdk): string {
-  const cached = verified.get(`${release}\0${sdk.wasmSdkId}`)
+  const key = JSON.stringify([release, sdk.wasmSdkId, swiftSdkOptions()])
+  const cached = verified.get(key)
   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'
+  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',
     stdio: ['ignore', 'pipe', 'pipe'],
   })
@@ -86,15 +128,99 @@ export function swiftToolchain(release: string, sdk: SwiftWasmSdk): string {
       `peach compiles Swift with the ${sdk.wasmSdkId} SDK, which ${swift} does not have.\n${swiftInstallSteps(release, sdk)}`,
     )
   }
-  verified.set(`${release}\0${sdk.wasmSdkId}`, bin)
+  verified.set(key, bin)
   return bin
 }
 
-/** the commands that install `release` and its wasm SDK on this host. */
+// 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}`)
+  }
+  const files = Object.entries(manifest.files)
+  if (files.length !== 15) 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',
+    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 the pinned compiler and SDK on this host. */
 export function swiftInstallSteps(release: string, wasmSdk: SwiftWasmSdk): string {
+  const sdkOptions = swiftSdkOptions()
+    .map((arg) => ` '${arg.replaceAll("'", "'\\''")}'`)
+    .join('')
+  if (release.includes('-custom-')) {
+    const archive = swiftHostCompilerArchive(release)
+    const directory = path.resolve(swiftToolchainBin(release), '../..')
+    return [
+      'install the pinned compiler and SDK:',
+      `  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}'`,
+      `  '${directory}/usr/bin/swift' sdk install ${wasmSdk.wasmSdkUrl} --checksum ${wasmSdk.wasmSdkChecksum}${sdkOptions}`,
+    ].join('\n')
+  }
   const version = release.replace(/^swift-/, '').toLowerCase()
   const downloads = `https://download.swift.org/swift-${version}`
-  const sdk = `swift sdk install ${wasmSdk.wasmSdkUrl} --checksum ${wasmSdk.wasmSdkChecksum}`
+  const sdk = `swift sdk install ${wasmSdk.wasmSdkUrl} --checksum ${wasmSdk.wasmSdkChecksum}${sdkOptions}`
   if (process.platform === 'darwin') {
     const swift = `~/Library/Developer/Toolchains/${release}.xctoolchain/usr/bin/swift`
     return [