peachsim 0.1.1625 → 0.1.1640

package/src/swift-standins.ts

@@ -12,19 +12,30 @@
 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 { isRecord } from './is-record'
+import { outputLockStdio } from './output-lock-stdio'
 import { parsePlistSource } from './plist'
 import {
   swiftDistributionAt,
+  swiftImportNames,
   swiftMacroPlugins,
   swiftModuleDigest,
   swiftModuleSdk,
   swiftPeachModules,
   swiftSdkPaths,
 } from './swift-compile'
-import { IOS_SDK_ID, objcView } from './swift-objc-standin'
+import {
+  IOS_SDK_ID,
+  NATIVE_GRAPH_ID,
+  OBJC_IMPORT_VERSION,
+  nativeInterfaceView,
+  objcView,
+  type ObjcSurface,
+} from './swift-objc-standin'
+import { swiftTargetModuleName } from './swift-package'
 import {
   STANDIN_EMIT_VERSION,
   STANDIN_IMPORTS,
@@ -33,11 +44,13 @@ import {
   type SwiftStandinBehaviors,
   type StandinBehavior,
 } from './swift-standin-emit'
+import { swiftEnvironment, 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')
+const WASI_EMULATION = ['_WASI_EMULATED_SIGNAL', '_WASI_EMULATED_MMAN']
+// 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__'
 
@@ -48,6 +61,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 {
@@ -61,12 +76,20 @@ 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
+}
+
+interface NativeFrameworkInputs {
+  dirs: string[]
+  digest: string
 }
 
 function exec(file: string, args: string[], cwd?: string): string {
   return execFileSync(file, args, {
     cwd,
     encoding: 'utf8',
+    env: swiftEnvironment(),
     maxBuffer: 256 * 1024 * 1024,
     stdio: ['ignore', 'pipe', 'pipe'],
   })
@@ -94,14 +117,20 @@ const digests = new Map<string, { stamp: string; digest: string }>()
 
 function treeDigest(root: string): string {
   const names: string[] = []
+  const ancestors = new Set<string>()
   const walk = (dir: string) => {
+    const resolved = fs.realpathSync(dir)
+    if (ancestors.has(resolved)) throw new Error(`cyclic header directory: ${dir}`)
+    ancestors.add(resolved)
     for (const entry of fs
       .readdirSync(dir, { withFileTypes: true })
       .sort((left, right) => (left.name < right.name ? -1 : 1))) {
       const full = path.join(dir, entry.name)
-      if (entry.isDirectory()) walk(full)
-      else if (entry.isFile()) names.push(path.relative(root, full))
+      const stat = entry.isSymbolicLink() ? fs.statSync(full) : entry
+      if (stat.isDirectory()) walk(full)
+      else if (stat.isFile()) names.push(path.relative(root, full))
     }
+    ancestors.delete(resolved)
   }
   walk(root)
   const stamp = names
@@ -217,8 +246,9 @@ const files = (dir: string, test: (name: string) => boolean): string[] =>
 /** the module surfaces an iOS simulator slice describes. */
 type Surface =
   | { kind: 'swift'; module: string; interface: string }
+  | (ObjcSurface & { kind: 'mixed'; 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
 
@@ -257,15 +287,27 @@ function surfaces(xcframeworkDir: string): Surface[] {
     )
     const chosen =
       interfaces.find((name) => name.startsWith('arm64-')) ?? interfaces[0] ?? null
+    const modulemap = path.join(framework, 'Modules', 'module.modulemap')
     if (chosen) {
-      found.push({
-        kind: 'swift',
-        module,
-        interface: path.join(swiftmodule, chosen),
-      })
+      const file = path.join(swiftmodule, chosen)
+      const underlying = [
+        ...fs
+          .readFileSync(file, 'utf8')
+          .matchAll(/^(?:@_exported[ \t]+)?import[ \t]+(\w+)[ \t]*$/gm),
+      ].some((match) => match[1] === module)
+      if (underlying) {
+        if (!fs.existsSync(modulemap))
+          throw new Error(`${module} imports its underlying module without a modulemap`)
+        found.push({
+          kind: 'mixed',
+          module,
+          interface: file,
+          modulemap,
+          headers: path.join(framework, 'Headers'),
+        })
+      } else found.push({ kind: 'swift', module, interface: file })
       continue
     }
-    const modulemap = path.join(framework, 'Modules', 'module.modulemap')
     if (fs.existsSync(modulemap))
       found.push(headerSurface(module, modulemap, path.join(framework, 'Headers')))
   }
@@ -281,6 +323,14 @@ function surfaces(xcframeworkDir: string): Surface[] {
   return found
 }
 
+export function standinsNeedNativeSdk(binaries: readonly SwiftPackageBinary[]): boolean {
+  return binaries.some(
+    (binary) =>
+      binary.publicHeaders === undefined &&
+      surfaces(xcframework(binary).dir).some((surface) => surface.kind === 'mixed'),
+  )
+}
+
 // the peach modules an interface imports, compiled for wasm: a distribution
 // ships them; a checkout builds the ones named into its own build directory,
 // with the flags scripts/build.sh uses, so the two share one build.
@@ -305,10 +355,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',
@@ -359,11 +411,14 @@ export function swiftInterfaceForWasm(text: string): string {
       ? rooted.replace(/^(?=import[ \t])/m, 'import Foundation\n')
       : rooted
   return foundation
-    .replace(/^(\/\/ swift-module-flags:.*)$/m, (flags) =>
-      flags
-        .replace(/-target \S+/, `-target ${TRIPLE}`)
-        .replace(/\s-enable-objc-interop\b/, '')
-        .replace(/\s-target-variant \S+/, ''),
+    .replace(
+      /^(\/\/ swift-module-flags:.*)$/m,
+      (flags) =>
+        flags
+          .replace(/-target \S+/, `-target ${TRIPLE}`)
+          .replace(/\s-enable-objc-interop\b/, '')
+          .replace(/\s-target-variant \S+/, '') +
+        ` ${WASI_EMULATION.map((name) => `-Xcc -D${name}`).join(' ')}`,
     )
     .replace(
       /@(?:objc(?:\s*\([^()]*\))?|objcMembers|nonobjc|IBOutlet|IBAction|IBInspectable|IBDesignable|_objcRuntimeName\([^()]*\))(?![\w(])/g,
@@ -377,17 +432,14 @@ function swiftStandin(
   toolchain: Toolchain,
   work: string,
   behavior: ReadonlyMap<string, StandinBehavior>,
+  siblings: ReadonlySet<string>,
 ): SwiftStandin {
   const text = swiftInterfaceForWasm(fs.readFileSync(surface.interface, 'utf8'))
   const search = path.join(work, 'interfaces')
   const moduleDir = path.join(search, `${surface.module}.swiftmodule`)
   fs.mkdirSync(moduleDir, { recursive: true })
   fs.writeFileSync(path.join(moduleDir, `${TRIPLE}.swiftinterface`), text)
-  const imports = [
-    ...text.matchAll(
-      /^(?:@_exported[ \t]+)?import[ \t]+(?:(?:struct|class|enum|protocol|typealias|func|var|let)[ \t]+)?(\w+)/gm,
-    ),
-  ].map((match) => match[1]!)
+  const imports = swiftImportNames(text)
   const wasm = wasmFlags(toolchain, imports)
   const out = path.join(work, 'graphs')
   fs.mkdirSync(out, { recursive: true })
@@ -418,6 +470,37 @@ function swiftStandin(
     toolchain,
     work,
     behavior,
+    [...new Set(imports)].filter((module) => siblings.has(module)),
+  )
+}
+
+function mixedStandin(
+  surface: Extract<Surface, { kind: 'mixed' }>,
+  binary: SwiftPackageBinary,
+  toolchain: Toolchain,
+  work: string,
+  behavior: ReadonlyMap<string, StandinBehavior>,
+  frameworkDirs: readonly string[],
+  siblings: ReadonlySet<string>,
+): SwiftStandin {
+  const view = nativeInterfaceView(surface, frameworkDirs, work)
+  const provided = new Set(swiftPeachModules(toolchain.moduleRoot))
+  const imports = [
+    ...new Set(swiftImportNames(fs.readFileSync(surface.interface, 'utf8'))),
+  ].filter(
+    (module) =>
+      module !== surface.module && (provided.has(module) || siblings.has(module)),
+  )
+  return graphStandin(
+    surface.module,
+    view.graphs,
+    view.values,
+    wasmFlags(toolchain, imports),
+    binary,
+    toolchain,
+    work,
+    behavior,
+    imports,
   )
 }
 
@@ -434,7 +517,10 @@ function wasmFlags(toolchain: Toolchain, imports: string[]): string[] {
     sysroot,
     '-resource-dir',
     resources,
+    // the sdk toolset's emulation defines, which raw swiftc does not read
+    ...WASI_EMULATION.flatMap((name) => ['-Xcc', `-D${name}`]),
     ...peachModuleDirs(toolchain, imports).flatMap((dir) => ['-I', dir]),
+    ...(toolchain.standinModules ? ['-I', toolchain.standinModules] : []),
   ]
 }
 
@@ -462,6 +548,9 @@ function objcStandin(
     toolchain,
     work,
     behavior,
+    binary.headerDependencies?.map((dependency) =>
+      swiftTargetModuleName(dependency.module),
+    ),
   )
 }
 
@@ -477,6 +566,7 @@ function graphStandin(
   toolchain: Toolchain,
   work: string,
   behavior: ReadonlyMap<string, StandinBehavior>,
+  imports: string[] = [],
 ): SwiftStandin {
   const paths = new Set(
     graphs.flatMap((graph) =>
@@ -500,6 +590,9 @@ function graphStandin(
       behavior,
       omit,
       plain,
+      inert: binary.publicHeaders !== undefined,
+      imports,
+      family: imports,
     })
     for (const entry of skipped) {
       if (behavior.has(entry.path))
@@ -510,23 +603,28 @@ function graphStandin(
     fs.writeFileSync(file, source)
     const check = spawnSync(
       path.join(toolchain.toolchainBin, 'swiftc'),
+      // emitting the module runs the diagnostics a typecheck skips, such as
+      // literal overflow, which the app's build of the stand-in reaches
       [
-        '-typecheck',
+        '-emit-module',
         '-parse-as-library',
         '-swift-version',
         '5',
         '-module-name',
         module,
         ...wasm,
+        '-emit-module-path',
+        path.join(work, `${module}.swiftmodule`),
         file,
       ],
-      { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 },
+      { encoding: 'utf8', env: swiftEnvironment(), maxBuffer: 256 * 1024 * 1024 },
     )
     if (check.status === 0)
       return {
         module,
         target: binary.target,
         files: { [`${module}.swift`]: source },
+        ...(imports.length ? { dependencies: imports } : {}),
       }
     const before = omit.size + plain.size
     const elsewhere: string[] = []
@@ -901,6 +999,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)
@@ -922,14 +1021,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'],
     },
@@ -969,30 +1072,91 @@ export function standinLibrary(
   throw new Error(`cargo built ${crate} for ${RUST_TARGET} but reported no ${library}`)
 }
 
-// source preflight shares project compilation's portable builder admission.
-// the complete resolved artifact travels as an input, including ignored local frameworks.
-function sourceBinaryStandins(
-  binary: SwiftPackageBinary,
+// source preflight admits the complete closure once, including ignored local
+// frameworks. target generation and prerequisite modules stay in that one job.
+function sourceStandins(
+  binaries: readonly SwiftPackageBinary[],
   toolchain: Toolchain,
   provided: ReadonlySet<string>,
   behavior: SwiftStandinBehaviors,
-): SwiftStandin[] | string {
+): SwiftStandins {
   const repo = path.resolve(toolchain.moduleRoot, '../..')
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'peach-standin-request-'))
+  fs.mkdirSync(cacheDir, { recursive: true })
+  const generation = standinGenerationInputs(binaries, toolchain, behavior)
+  const cached = path.join(
+    cacheDir,
+    'closures',
+    `${key(generation, JSON.stringify([...provided].sort()))}.json`,
+  )
+  const targets = new Set(binaries.map((binary) => binary.target))
+  if (fs.existsSync(cached))
+    return readStandinResults(
+      JSON.parse(fs.readFileSync(cached, 'utf8')),
+      generation,
+      targets,
+    )
+  const work = fs.mkdtempSync(path.join(cacheDir, 'request-'))
   try {
-    const artifact = xcframework(binary)
-    const local = { ...binary, dir: artifact.dir, url: null, checksum: null }
-    const generation = standinGenerationInputs([local], toolchain, behavior)
+    const artifact = path.join(work, 'artifacts')
+    fs.mkdirSync(artifact)
+    const local: SwiftPackageBinary[] = []
+    const gaps = new Map<string, string>()
+    const headers = new Map<string, string>()
+    for (const [index, binary] of binaries.entries()) {
+      try {
+        if (binary.publicHeaders !== undefined) {
+          const copyHeader = (relative: string) => {
+            const source = fs.realpathSync(path.join(binary.dir, relative))
+            let destination = headers.get(source)
+            if (destination === undefined) {
+              destination = `headers/${headers.size}`
+              fs.cpSync(source, path.join(artifact, destination), {
+                recursive: true,
+                dereference: true,
+              })
+              headers.set(source, destination)
+            }
+            return destination
+          }
+          local.push({
+            ...binary,
+            dir: artifact,
+            url: null,
+            checksum: null,
+            publicHeaders: copyHeader(binary.publicHeaders),
+            headerDependencies: (binary.headerDependencies ?? []).map((dependency) => ({
+              module: dependency.module,
+              path: copyHeader(dependency.path),
+            })),
+          })
+        } else {
+          const resolved = xcframework(binary)
+          const dir = path.join(artifact, String(index), path.basename(resolved.dir))
+          fs.cpSync(resolved.dir, dir, { recursive: true, dereference: true })
+          local.push({ ...binary, dir, url: null, checksum: null })
+        }
+      } catch (error) {
+        gaps.set(binary.target, error instanceof Error ? error.message : String(error))
+      }
+    }
+    if (local.length === 0) return { standins: [], gaps }
+    const preparedGeneration = standinGenerationInputs(local, toolchain, behavior)
+    if (generation !== standinGenerationInputs(binaries, toolchain, behavior))
+      throw new Error('Swift stand-in inputs changed during preparation')
     const request = path.join(work, 'request.json')
     const delivery = path.join(work, 'delivery')
     fs.writeFileSync(
       request,
       JSON.stringify({
-        binary: local,
+        binaries: local.map((binary) => ({
+          ...binary,
+          dir: path.relative(artifact, binary.dir) || '.',
+        })),
         provided: [...provided],
         behavior,
-        generation,
+        generation: preparedGeneration,
         release: toolchain.release,
+        native: standinsNeedNativeSdk(local),
       }),
     )
     const build = spawnSync(
@@ -1002,56 +1166,104 @@ function sourceBinaryStandins(
         '--request',
         request,
         '--artifact',
-        artifact.dir,
+        artifact,
         '--delivery-dir',
         delivery,
       ],
-      { cwd: repo, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
+      {
+        cwd: repo,
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+        stdio: outputLockStdio(['ignore', 'pipe', 'pipe']),
+      },
     )
     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'}`,
+        `source stand-in build for ${local.map((binary) => binary.target).join(', ')} 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}`,
-      )
+      throw new Error('source stand-in builder returned no standins.json')
     const receipt: unknown = JSON.parse(fs.readFileSync(output, 'utf8'))
-    if (
-      !receipt ||
-      typeof receipt !== 'object' ||
-      !('generation' in receipt) ||
-      receipt.generation !== generation ||
-      !('result' in receipt)
-    )
-      throw new Error('Swift stand-in builder source differs from the caller')
-    const result = receipt.result
-    if (typeof result === 'string') throw new Error(result)
-    if (
-      !Array.isArray(result) ||
-      !result.every(
-        (item) =>
-          item &&
-          typeof item === 'object' &&
-          typeof item.module === 'string' &&
-          typeof item.target === 'string' &&
-          item.target === binary.target &&
-          item.files &&
-          typeof item.files === 'object' &&
-          !Array.isArray(item.files) &&
-          Object.values(item.files).every((text) => typeof text === 'string'),
-      )
+    const result = readStandinResults(
+      receipt,
+      preparedGeneration,
+      new Set(local.map((binary) => binary.target)),
     )
-      throw new Error('invalid Swift stand-in builder result')
+    if (generation !== standinGenerationInputs(binaries, toolchain, behavior))
+      throw new Error('Swift stand-in inputs changed during generation')
+    for (const [target, reason] of gaps) result.gaps.set(target, reason)
+    // failures retry against the per-target generation cache on the builder.
+    // only a complete successful closure skips the next admission entirely.
+    if (result.gaps.size === 0 && isRecord(receipt)) {
+      fs.mkdirSync(path.dirname(cached), { recursive: true })
+      const pending = `${cached}.${process.pid}.tmp`
+      fs.writeFileSync(pending, JSON.stringify({ ...receipt, generation }))
+      fs.renameSync(pending, cached)
+    }
     return result
   } finally {
     fs.rmSync(work, { recursive: true, force: true })
   }
 }
 
+function readStandinResults(
+  receipt: unknown,
+  generation: string,
+  targets: ReadonlySet<string>,
+): SwiftStandins {
+  if (!isRecord(receipt) || receipt.generation !== generation)
+    throw new Error('Swift stand-in builder source differs from the caller')
+  if (!Array.isArray(receipt.results) || receipt.results.length !== targets.size)
+    throw new Error('invalid Swift stand-in builder results')
+  const standins: SwiftStandin[] = []
+  const gaps = new Map<string, string>()
+  const seen = new Set<string>()
+  for (const entry of receipt.results) {
+    if (
+      !isRecord(entry) ||
+      typeof entry.target !== 'string' ||
+      !targets.has(entry.target) ||
+      seen.has(entry.target)
+    )
+      throw new Error('invalid Swift stand-in builder target')
+    seen.add(entry.target)
+    if (typeof entry.result === 'string') {
+      gaps.set(entry.target, entry.result)
+      continue
+    }
+    if (!Array.isArray(entry.result))
+      throw new Error('invalid Swift stand-in builder result')
+    for (const item of entry.result) {
+      if (
+        !isRecord(item) ||
+        typeof item.module !== 'string' ||
+        item.target !== entry.target ||
+        !isRecord(item.files) ||
+        !Object.values(item.files).every((text) => typeof text === 'string') ||
+        (item.dependencies !== undefined &&
+          (!Array.isArray(item.dependencies) ||
+            !item.dependencies.every((name) => typeof name === 'string')))
+      )
+        throw new Error('invalid Swift stand-in builder result')
+      const files: Record<string, string> = {}
+      for (const [name, text] of Object.entries(item.files)) {
+        if (typeof text !== 'string') throw new Error('invalid Swift stand-in file')
+        files[name] = text
+      }
+      standins.push({
+        module: item.module,
+        target: entry.target,
+        files,
+        ...(item.dependencies === undefined ? {} : { dependencies: item.dependencies }),
+      })
+    }
+  }
+  return { standins, gaps }
+}
+
 const built = new Map<string, SwiftStandin[] | string>()
 
 /** what stand-ins are generated from besides the surfaces' files: the
@@ -1066,20 +1278,23 @@ export function standinGenerationInputs(
   const { moduleRoot, release } = toolchain
   const sdk = swiftModuleSdk(moduleRoot)
   const parts = [
-    'standin/v4',
+    'standin/v9',
     release,
     sdk.wasmSdkId,
     sdk.wasmSdkChecksum,
     swiftModuleDigest(moduleRoot).toString('hex'),
     `emit/${STANDIN_EMIT_VERSION}`,
     `ios-sdk/${IOS_SDK_ID}`,
+    `objc-import/${OBJC_IMPORT_VERSION}`,
     // a released cli can change the emitter without anyone bumping the constant
     `cli/${getCliVersion()}`,
   ]
   const modules = new Set(
     binaries.flatMap((binary) => {
       try {
-        return surfaces(xcframework(binary).dir).map((surface) => surface.module)
+        return binary.publicHeaders !== undefined
+          ? [swiftTargetModuleName(binary.target)]
+          : surfaces(xcframework(binary).dir).map((surface) => surface.module)
       } catch {
         return []
       }
@@ -1100,13 +1315,36 @@ export function standinGenerationInputs(
       ),
     )
   for (const binary of binaries) {
+    if (
+      binary.publicHeaders !== undefined &&
+      swiftTargetModuleName(binary.target) !== binary.target
+    )
+      parts.push(`module/${swiftTargetModuleName(binary.target)}`)
     try {
+      if (
+        binary.publicHeaders === undefined &&
+        surfaces(xcframework(binary).dir).some((surface) => surface.kind === 'swift')
+      )
+        parts.push(`interface-emulation/${WASI_EMULATION.join(',')}`)
+      if (
+        binary.publicHeaders === undefined &&
+        surfaces(xcframework(binary).dir).some((surface) => surface.kind === 'mixed')
+      )
+        parts.push(`native-graph/${NATIVE_GRAPH_ID}`)
       parts.push(
         binary.target,
         binary.source,
         binary.url ?? '',
         binary.checksum ?? '',
-        xcframework(binary).digest,
+        binary.publicHeaders !== undefined
+          ? [
+              treeDigest(path.join(binary.dir, binary.publicHeaders)),
+              ...(binary.headerDependencies ?? []).map(
+                (dependency) =>
+                  `${swiftTargetModuleName(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
@@ -1132,6 +1370,8 @@ function binaryStandins(
   toolchain: Toolchain,
   provided: ReadonlySet<string>,
   behavior: SwiftStandinBehaviors,
+  frameworks: NativeFrameworkInputs,
+  siblings: ReadonlySet<string>,
 ): SwiftStandin[] | string {
   if (provided.has(binary.target)) return []
   // a local artifact a script downloads or builds is absent from a fresh
@@ -1139,17 +1379,56 @@ 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 module = swiftTargetModuleName(binary.target)
+      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 ${module} {\n${roots.map((file) => `  header "${file}"`).join('\n')}\n  export *\n}\n`,
+      )
+      all = [
+        {
+          kind: 'objc',
+          module,
+          modulemap,
+          headers,
+          dependencies: binary.headerDependencies?.map((dependency) => ({
+            module: swiftTargetModuleName(dependency.module),
+            headers: path.join(binary.dir, dependency.path),
+          })),
+        },
+      ]
+      digest = [
+        treeDigest(headers),
+        ...(binary.headerDependencies ?? []).map(
+          (dependency) =>
+            `${swiftTargetModuleName(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'
   }
@@ -1159,11 +1438,14 @@ function binaryStandins(
     standinGenerationInputs([binary], toolchain, behavior),
   )
   hash.update(digest)
+  hash.update([...siblings].sort().join('\0'))
+  if (found.some((surface) => surface.kind === 'mixed')) hash.update(frameworks.digest)
   for (const surface of found) {
     hash.update(`${surface.kind}\0${surface.module}\0`)
     for (const file of surface.kind === 'swift'
       ? [surface.interface]
       : [
+          ...(surface.kind === 'mixed' ? [surface.interface] : []),
           surface.modulemap,
           ...files(surface.headers, (name) => name.endsWith('.h')).map((file) =>
             path.join(surface.headers, file),
@@ -1173,54 +1455,60 @@ 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') &&
-      !swiftDistributionAt(toolchain.moduleRoot)
-        ? sourceBinaryStandins(binary, toolchain, provided, behavior)
-        : found.map((surface) => {
-            const dir = path.join(work, surface.module)
-            try {
-              if (surface.kind === 'c' && configured.has(surface.module))
-                throw new Error(
-                  "Configured behavior requires the framework's Swift declarations",
-                )
-              return surface.kind === 'swift'
-                ? swiftStandin(
-                    surface,
-                    binary,
-                    toolchain,
-                    dir,
-                    new Map(Object.entries(configured.get(surface.module) ?? {})),
-                  )
-                : surface.kind === 'objc'
-                  ? objcStandin(
-                      surface,
-                      binary,
-                      toolchain,
-                      dir,
-                      new Map(Object.entries(configured.get(surface.module) ?? {})),
-                    )
-                  : cStandin(surface, binary, toolchain, dir)
-            } catch (error) {
-              throw new Error(
-                `no stand-in for ${surface.module}: ${error instanceof Error && !('stderr' in error) ? error.message : failure(error)}`,
+    result = found.map((surface) => {
+      const dir = path.join(work, surface.module)
+      try {
+        if (surface.kind === 'c' && configured.has(surface.module))
+          throw new Error(
+            "Configured behavior requires the framework's Swift declarations",
+          )
+        return surface.kind === 'mixed'
+          ? mixedStandin(
+              surface,
+              binary,
+              toolchain,
+              dir,
+              new Map(Object.entries(configured.get(surface.module) ?? {})),
+              frameworks.dirs,
+              siblings,
+            )
+          : surface.kind === 'swift'
+            ? swiftStandin(
+                surface,
+                binary,
+                toolchain,
+                dir,
+                new Map(Object.entries(configured.get(surface.module) ?? {})),
+                siblings,
               )
-            }
-          })
+            : surface.kind === 'objc'
+              ? objcStandin(
+                  surface,
+                  binary,
+                  toolchain,
+                  dir,
+                  new Map(Object.entries(configured.get(surface.module) ?? {})),
+                )
+              : cStandin(surface, binary, toolchain, dir)
+      } catch (error) {
+        throw new Error(
+          `no stand-in for ${surface.module}: ${error instanceof Error && !('stderr' in error) ? error.message : failure(error)}`,
+        )
+      }
+    })
     if (typeof result === 'string') throw new Error(result)
     fs.mkdirSync(path.dirname(cached), { recursive: true })
     // publish a complete entry so concurrent workspaces never read partial json.
@@ -1256,12 +1544,138 @@ export function swiftStandins(
   provided: ReadonlySet<string> = new Set(),
   behavior: SwiftStandinBehaviors = {},
 ): SwiftStandins {
+  const requested = binaries.filter((binary) => !provided.has(binary.target))
+  if (requested.length === 0) return { standins: [], gaps: new Map() }
+  if (
+    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') &&
+    !swiftDistributionAt(toolchain.moduleRoot)
+  )
+    return sourceStandins(requested, toolchain, provided, behavior)
   const standins: SwiftStandin[] = []
   const gaps = new Map<string, string>()
+  fs.mkdirSync(cacheDir, { recursive: true })
+  const modules = fs.mkdtempSync(path.join(cacheDir, 'modules-'))
+  const frameworkDirs = new Set<string>()
+  const frameworkInputs: string[] = []
+  const byModule = new Map(
+    binaries.map((binary) => [swiftTargetModuleName(binary.target), binary]),
+  )
+  // the modules each binary's swift interfaces import
+  const interfaceImports = new Map<SwiftPackageBinary, Set<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)
+    if (binary.publicHeaders !== undefined) continue
+    try {
+      const artifact = xcframework(binary)
+      frameworkInputs.push(`${binary.target}\0${artifact.digest}`)
+      const imports = new Set<string>()
+      interfaceImports.set(binary, imports)
+      for (const surface of surfaces(artifact.dir)) {
+        byModule.set(surface.module, binary)
+        if (surface.kind === 'swift' || surface.kind === 'mixed')
+          for (const module of swiftImportNames(
+            fs.readFileSync(surface.interface, 'utf8'),
+          ))
+            imports.add(module)
+        if (surface.kind === 'c') continue
+        frameworkDirs.add(
+          surface.kind === 'swift'
+            ? path.resolve(surface.interface, '../../../..')
+            : path.resolve(surface.modulemap, '../../..'),
+        )
+      }
+    } catch {
+      // the target reports its artifact gap when visited below.
+    }
+  }
+  const generatedToolchain = { ...toolchain, standinModules: modules }
+  const frameworks: NativeFrameworkInputs = {
+    dirs: [...frameworkDirs].sort(),
+    digest: createHash('sha256').update(frameworkInputs.sort().join('\0')).digest('hex'),
+  }
+  // another binary's module a swift interface imports: its stand-in is built
+  // first and imported, as the vendor framework imports the other framework
+  const siblings = new Map(
+    binaries.map((binary) => [
+      binary,
+      new Set(
+        [...(interfaceImports.get(binary) ?? [])].filter((module) => {
+          const owner = byModule.get(module)
+          return owner !== undefined && owner !== binary && !provided.has(module)
+        }),
+      ),
+    ]),
+  )
+  const prerequisites = new Set(
+    binaries.flatMap((binary) => [
+      ...(binary.headerDependencies ?? []).map((dependency) =>
+        swiftTargetModuleName(dependency.module),
+      ),
+      ...siblings.get(binary)!,
+    ]),
+  )
+  const visited = new Set<string>()
+  const visit = (binary: SwiftPackageBinary) => {
+    if (visited.has(binary.target)) return
+    visited.add(binary.target)
+    for (const module of [
+      ...(binary.headerDependencies ?? []).map((dependency) =>
+        swiftTargetModuleName(dependency.module),
+      ),
+      ...siblings.get(binary)!,
+    ]) {
+      const target = byModule.get(module)
+      if (target) visit(target)
+    }
+    const result = binaryStandins(
+      binary,
+      generatedToolchain,
+      provided,
+      behavior,
+      frameworks,
+      siblings.get(binary)!,
+    )
+    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 }
 }