Forgeyard Swift CI/CD System & Architecture
Document type: Dedicated language ecosystem System & Architecture
Project: Forgeyard CI/CD
Subsystem: First-class Swift build, test, package, Apple-platform, Linux, native interop, reproducibility, signing, distribution, and release integration
Implementation direction: Rust-first Forgeyard core with native integration to Swift toolchains, Swift Package Manager, Xcode/Apple SDKs, Clang/LLVM, C/C++/Objective-C interop, Apple signing/notarization, and Forgeyard device/runner pools
Status: Target production architecture
Relationship to Forgeyard: This document defines the dedicated Swift subsystem that integrates with Forgeyard’s pipeline IR, hermetic build system, scheduler, runners, CAS, functional store, provenance, packaging, distribution, and deployment architecture.
1. Purpose
Swift requires a dedicated Forgeyard architecture because Swift exists in two significantly different environments:
Portable/server-side Swift
+
Apple-platform Swift
These share the Swift compiler and SwiftPM model but differ materially in:
- SDK availability;
- Objective-C runtime integration;
- platform frameworks;
- Xcode dependency;
- Apple SDKs;
- signing;
- entitlements;
- provisioning;
- simulator/device execution;
- notarization;
- application packaging;
- architecture matrices;
- SwiftUI/UIKit/AppKit/watchOS/tvOS/visionOS integration.
A Swift build can depend on:
- Swift compiler version;
- Swift standard library/runtime;
- Clang/LLVM toolchain;
Package.swift;Package.resolved;- SwiftPM plugin graph;
- macro implementation packages;
- binary targets;
- Git dependencies;
- path dependencies;
- target triples;
- SDK;
- deployment target;
- architecture;
- build configuration;
- compiler flags;
- linker flags;
- C/C++ headers;
- module maps;
- Objective-C headers/modules;
- system libraries;
- pkg-config;
- Xcode version;
- Apple SDK revision;
- signing identities;
- provisioning profiles;
- entitlements;
- environment variables;
- generated code;
- build-tool plugins;
- macro plugins;
- local SwiftPM caches;
- DerivedData;
- arbitrary host SDK state.
Forgeyard therefore needs a subsystem whose central rule is:
A Swift build is defined by source + complete Swift toolchain + SwiftPM dependency graph + target/platform contract + C/Objective-C/C++ interop closure + compiler/plugin/macro graph + controlled environment.
For Apple releases, that expands to:
Apple Swift release identity additionally includes Xcode/Apple SDK/deployment target/platform configuration, while signing identities and provisioning remain late-bound release effects rather than source build identity.
2. Architectural Objectives
Forgeyard Swift MUST:
- support Swift packages;
- support Swift libraries;
- support Swift executables;
- support SwiftPM workspaces/packages;
- support
Package.swift; - support
Package.resolved; - support Git dependencies;
- support local/path dependencies;
- support binary targets;
- support SwiftPM resources;
- support SwiftPM build-tool plugins;
- support Swift macros;
- support C interop;
- support Objective-C interop on Apple platforms;
- support C++ interop where toolchain/project permits;
- support system-library targets;
- support Linux Swift;
- support macOS Swift;
- support iOS;
- support iPadOS through iOS target semantics;
- support watchOS;
- support tvOS;
- support visionOS;
- support simulators;
- support physical Apple devices;
- support XCTest;
- support Swift Testing;
- support code coverage;
- support linting/formatting adapters;
- support API compatibility checks;
- support documentation generation;
- support XCFrameworks;
- support static/dynamic libraries;
- support application bundles;
- support deterministic unsigned artifacts where practical;
- support late codesigning;
- support notarization;
- support App Store packaging/publishing adapters;
- support Swift package publishing/release workflows;
- support remote scheduling;
- support Forgeyard Apple runner pools;
- support device-lab integration;
- support reproducibility verification;
- support SBOM/provenance;
- remain local-first for non-Apple and local Apple development where toolchains are available.
3. Non-Goals
Forgeyard does not replace:
- Swift compiler;
- Swift Package Manager;
- Xcode;
- Apple SDKs;
- Clang;
- LLDB;
- XCTest;
- Swift Testing;
- codesign;
- notarization services;
- App Store distribution mechanisms.
Forgeyard locks, isolates, orchestrates, verifies, caches, packages, signs, and distributes their outputs.
4. High-Level Architecture
flowchart TB
Src["Swift Source"]
Detect["Swift Detector"]
Model["SwiftProjectSpec"]
SwiftTC["Swift Toolchain Resolver"]
SwiftPM["SwiftPM Resolver"]
Plugins["Macro / Plugin Resolver"]
Native["C / ObjC / C++ Resolver"]
Platform["Target Platform / SDK Resolver"]
Lock["Swift Lock Graph"]
Graph["Build / Test Graph"]
Sched["Forgeyard Scheduler"]
Runner["Swift-Capable Runner"]
Sand["Hermetic Sandbox"]
Build["SwiftPM / Xcode Build Adapter"]
SwiftC["swiftc"]
NativeBuild["Clang / Native Build"]
Tests["XCTest / Swift Testing / Analysis"]
CAS["Forgeyard CAS + Functional Store"]
Repro["Reproducibility Verifier"]
Pack["Library / XCFramework / App Package"]
Sign["Signing / Notarization"]
Prov["SBOM / Provenance"]
Dist["Promotion / Distribution"]
Src --> Detect
Detect --> Model
Model --> SwiftTC
Model --> SwiftPM
Model --> Plugins
Model --> Native
Model --> Platform
SwiftTC --> Lock
SwiftPM --> Lock
Plugins --> Lock
Native --> Lock
Platform --> Lock
Lock --> Graph
Graph --> Sched
Sched --> Runner
Runner --> Sand
Sand --> Build
Build --> SwiftC
Build --> NativeBuild
SwiftC --> Tests
NativeBuild --> Tests
SwiftC --> CAS
NativeBuild --> CAS
Tests --> CAS
CAS --> Repro
Repro --> Pack
Pack --> Sign
Sign --> Prov
Prov --> Dist
5. Suggested Forgeyard Workspace
crates/
├── forgeyard-swift/
├── forgeyard-swift-model/
├── forgeyard-swift-detect/
├── forgeyard-swift-toolchain/
├── forgeyard-swift-swiftpm/
├── forgeyard-swift-lock/
├── forgeyard-swift-deps/
├── forgeyard-swift-macros/
├── forgeyard-swift-plugins/
├── forgeyard-swift-native/
├── forgeyard-swift-clang/
├── forgeyard-swift-objc/
├── forgeyard-swift-cxx/
├── forgeyard-swift-test/
├── forgeyard-swift-analysis/
├── forgeyard-swift-coverage/
├── forgeyard-swift-doc/
├── forgeyard-swift-linux/
├── forgeyard-swift-apple/
├── forgeyard-swift-xcode/
├── forgeyard-swift-xcframework/
├── forgeyard-swift-signing/
├── forgeyard-swift-package/
├── forgeyard-swift-publish/
└── forgeyard-swift-provenance/
The architecture is capability-based; physical crates may later be consolidated.
6. Core Domain Model
#![allow(unused)]
fn main() {
pub struct SwiftProjectSpec {
pub source: SourceRef,
pub package: SwiftPackageSpec,
pub toolchain: SwiftToolchainRequest,
pub dependencies: SwiftDependencyPolicy,
pub target: SwiftTargetSpec,
pub native: SwiftNativeInteropPolicy,
pub plugins: SwiftPluginPolicy,
pub macros: SwiftMacroPolicy,
pub testing: SwiftTestPolicy,
pub analysis: SwiftAnalysisPolicy,
pub reproducibility: ReproducibilityPolicy,
}
}7. Strong Types
#![allow(unused)]
fn main() {
pub struct SwiftToolchainId(Digest);
pub struct SwiftPackageGraphId(Digest);
pub struct SwiftPluginGraphId(Digest);
pub struct SwiftMacroGraphId(Digest);
pub struct AppleSdkId(Digest);
pub struct XcodeId(Digest);
pub enum SwiftPlatform {
Linux,
MacOS,
IOS,
WatchOS,
TvOS,
VisionOS,
}
}8. Target Model
#![allow(unused)]
fn main() {
pub struct SwiftTargetSpec {
pub platform: SwiftPlatform,
pub architecture: Architecture,
pub deployment_target: Option<AppleDeploymentTarget>,
pub sdk: Option<AppleSdkId>,
pub simulator: bool,
}
}9. Project Detection
Detect:
Package.swift
Package.resolved
Sources/
Tests/
Plugins/
.swiftpm/
*.xcodeproj
*.xcworkspace
*.entitlements
Info.plist
Also detect:
SwiftPM package
Xcode application
framework
XCFramework producer
command-line executable
mixed Swift/C
mixed Swift/Objective-C
mixed Swift/C++
macro target
plugin target
binary target
system library target
10. Package.swift
Package.swift is executable Swift package description code interpreted by SwiftPM.
Forgeyard treats both:
Package.swift content
+
SwiftPM/toolchain semantics
as build graph inputs.
11. Package Description Identity
Forgeyard records:
tools version
package name
platform requirements
products
targets
dependencies
resources
plugins
Swift settings
C settings
C++ settings
linker settings
The exact manifest digest is part of source identity.
12. Package.resolved
For application/release-oriented package graphs, strict Forgeyard builds should preserve the resolved dependency state.
Forgeyard adds an outer immutable lock that includes:
resolved revision/version
fetched source content digest
toolchain identity
binary target digests
plugin/macro graph
13. Outer Swift Lock
Example:
swift: (
toolchain: (
version: "locked",
swiftc: "blake3:...",
stdlib: "blake3:...",
clang: "blake3:...",
),
package_resolved: "blake3:...",
dependency_graph: "blake3:...",
target: (
platform: MacOS,
architecture: Arm64,
sdk: "blake3:...",
),
)
14. Swift Toolchain Identity
A complete Swift toolchain can include:
swift
swiftc
SwiftPM
Swift standard library
Swift runtime
Clang
LLVM tools
module support libraries
SDK overlays
platform runtime compatibility libraries
Version string alone is insufficient.
15. Toolchain Modes
#![allow(unused)]
fn main() {
pub enum SwiftToolchainMode {
LockedManaged,
PlatformProvided,
AuditedHost,
}
}Linux can use strongly managed toolchains.
Apple builds may need platform-provided Xcode toolchains, but Forgeyard fingerprints them explicitly.
16. Toolchain Trust
#![allow(unused)]
fn main() {
pub enum SwiftToolchainTrust {
Unverified,
DigestVerified,
VendorVerified,
OrganizationApproved,
Revoked,
}
}17. Swift Language Version
Explicit if project/toolchain config sets it.
The compiler/toolchain remains the primary semantic authority.
18. SwiftPM Semantic Authority
Forgeyard MUST NOT reimplement SwiftPM dependency or target semantics.
Use the locked SwiftPM/toolchain to compute:
package graph
target graph
platform conditions
product graph
plugin graph
binary target relationships
Forgeyard then persists and verifies the result.
19. Dependency Sources
Support:
Git repository
local path
binary target
system library target
workspace/local package
20. Git Dependencies
Resolve:
repository
requested range/ref
exact revision
tree/content digest
Production builds never follow mutable branch state after lock.
21. Local Dependencies
Path dependencies must resolve inside:
source snapshot
or
explicit StoreRef
Never arbitrary machine-local paths.
22. Binary Targets
Binary targets such as packaged frameworks/artifacts are immutable inputs.
Forgeyard records:
URL/source
checksum
artifact digest
platform slices
architecture slices
23. Binary Target Validation
Validate:
declared checksum
archive safety
target platform
architectures
library/module metadata
24. System Library Targets
SwiftPM system-library targets often rely on:
pkg-config
module maps
system headers
system libraries
These must integrate with Forgeyard C/C++ native closure.
25. pkg-config
Forgeyard synthesizes:
PKG_CONFIG_PATH
PKG_CONFIG_LIBDIR
PKG_CONFIG_SYSROOT_DIR
from declared native dependencies.
No random host library discovery in strict builds.
26. C Interop
Swift imports C modules through Clang module machinery.
Inputs:
headers
module map
Clang
target
sysroot/SDK
defines
include paths
native libraries
27. Objective-C Interop
Apple-platform Swift can interoperate with Objective-C.
Identity includes:
Objective-C headers/modules
Clang
Apple SDK
frameworks
bridging headers where used
module maps
deployment target
28. Bridging Headers
If used:
bridging header content
transitive headers
compiler flags
are build inputs.
29. C++ Interop
Where Swift/C++ interop is enabled/configured:
C++ standard
Clang/C++ ABI
headers/modules
stdlib
compiler flags
target ABI
becomes part of derivation.
Delegate native ABI/toolchain validation to Forgeyard C/C++ subsystem.
30. Clang Dependency
Swift’s native interop is tightly connected to Clang.
Clang/toolchain identity is therefore part of Swift toolchain/platform closure when C-family interop is used.
31. Native Closure
Swift derivation
+
C/C++/Objective-C toolchain
+
sysroot/SDK
+
native libraries
+
module maps
=
native Swift derivation
32. Swift Macros
Swift macros are compile-time executable dependencies.
Forgeyard treats macro implementations as host-toolchain build outputs and explicit compiler inputs.
33. Macro Identity
macro package source
dependencies
Swift toolchain
enabled features/config
host platform
34. Macro Sandbox
Macro/plugin execution should occur under controlled build process boundaries.
Any external subprocess/network/filesystem behavior is subject to Forgeyard policy where technically observable/enforceable.
35. SwiftPM Plugins
Build-tool/command plugins are executable build-time code.
Treat similarly to build scripts in other ecosystems.
36. Plugin Identity
plugin source
package dependency graph
Swift toolchain
plugin permissions/policy
declared/generated outputs
37. Plugin Network Policy
Strict realization:
network denied
unless a plugin is explicitly classified as non-hermetic and run outside release derivation.
38. Generated Source
Generated Swift/C/ObjC/C++ source is an explicit output.
Two modes:
GenerateDuringBuild
CommittedAndVerify
39. Resources
SwiftPM resources become explicit source inputs.
Validate:
declared path
copy/process semantics
target association
case sensitivity
40. Build Configuration
Strong model:
#![allow(unused)]
fn main() {
pub enum SwiftBuildConfiguration {
Debug,
Release,
Custom(ProfileName),
}
}41. Compiler Options
Separate:
project Swift settings
Forgeyard reproducibility settings
platform settings
analysis-only settings
Effective command/config must be inspectable.
42. Environment Synthesis
Forgeyard controls:
PATH
HOME
TMPDIR
LANG
LC_ALL
TZ
SDKROOT where applicable
DEVELOPER_DIR for Apple
SWIFT_* variables that affect build
CC/CXX for interop
PKG_CONFIG_*
Do not inherit ambient host values blindly.
43. HOME Isolation
Synthetic HOME prevents hidden:
SwiftPM caches
Xcode user settings
credentials
toolchain config
from affecting build.
44. SwiftPM Cache
Mutable acceleration only.
Forgeyard source of truth remains:
locked source graph
toolchain identity
CAS/store objects
45. Build Directory
Use isolated:
.build/
or controlled build location per derivation.
Do not reuse arbitrary developer output state for release correctness.
46. Offline Build
Architecture:
resolve
↓
fetch packages/binaries
↓
verify
↓
materialize cache/store
↓
build with network denied
47. Linux Swift
Linux Swift support should be the strongest hermetic baseline because it can avoid Xcode-specific constraints.
Toolchain includes:
Swift compiler
Swift runtime
Clang
libc
C++ stdlib where interop uses it
sysroot
pkg-config/native closure
48. Linux Runtime Closure
Validate:
ELF interpreter
DT_NEEDED
RPATH/RUNPATH
Swift runtime libs
native libs
49. Linux Static/Dynamic Linking
Do not assume all Swift runtime components can/should be statically linked.
Model actual runtime closure.
50. Linux Packaging
Potential:
tar.zst
deb
rpm
OCI
Forgeyard bundle
51. Apple Build Architecture
Apple target builds require an explicit platform contract:
Xcode
Swift compiler
Clang
Apple SDK
deployment target
architecture
platform
simulator/device
framework availability
52. Xcode Identity
#![allow(unused)]
fn main() {
pub struct XcodeToolchainContract {
pub xcode: XcodeId,
pub swift: SwiftToolchainId,
pub sdk: AppleSdkId,
pub platform: SwiftPlatform,
}
}53. Xcode Is Not Just a Version String
Fingerprint relevant:
Xcode build
Swift compiler
Clang
SDK
tool locations
platform support
54. DEVELOPER_DIR
Forgeyard explicitly sets/controls Xcode selection.
Do not inherit arbitrary selected Xcode.
55. Apple SDK Identity
An Apple SDK contains:
headers
framework stubs
module interfaces
platform metadata
toolchain compatibility information
Treat as explicit platform input.
56. Deployment Target
Examples:
macOS minimum
iOS minimum
watchOS minimum
tvOS minimum
visionOS minimum
Deployment target affects:
available APIs
linking
runtime compatibility
and belongs in derivation identity.
57. Architecture
Apple architectures:
arm64
x86_64 for simulator/legacy contexts where applicable
are explicit.
58. Simulator vs Device
These are distinct targets.
Do not treat:
arm64-ios-simulator
as equivalent to:
arm64-ios-device
because platform ABI/runtime differs.
59. macOS
macOS Swift builds may produce:
CLI executable
framework
dynamic library
application bundle
package
60. iOS
iOS builds may produce:
app bundle
framework
XCFramework slice
test bundle
and require device/simulator distinctions.
61. watchOS
Same architectural model with watchOS-specific SDK/deployment/device constraints.
62. tvOS
Same with tvOS SDK/runtime constraints.
63. visionOS
Model as independent Apple platform contract.
Do not collapse into iOS.
64. Xcode Projects
Forgeyard should support both:
pure SwiftPM
Xcode project/workspace
where needed.
65. Xcode Project Inputs
Track:
project.pbxproj
workspace metadata
schemes
build settings
configuration
entitlements
Info.plist
asset catalogs
Swift package references
66. Xcode Scheme
Selected scheme/configuration is explicit.
67. Build Settings
Effective Xcode settings affecting output become derivation inputs.
Do not rely solely on project-file digest if environment overrides alter them.
68. DerivedData
Mutable acceleration.
Use isolated/controlled DerivedData location per cache namespace.
Never source of truth.
69. SwiftPM in Xcode
If Xcode resolves Swift packages, Forgeyard must still persist the exact package graph and fetched content identities.
70. XCTest
First-class test engine.
Supports:
unit
integration
UI test adapter via Xcode/device infrastructure
71. Swift Testing
Support as first-class modern Swift testing framework where project/toolchain uses it.
The framework/toolchain version is tied to Swift toolchain/project dependencies.
72. Test Plan
#![allow(unused)]
fn main() {
pub struct SwiftTestPlan {
pub suites: Vec<SwiftTestSuite>,
pub target: SwiftTestTarget,
pub shards: u32,
pub coverage: CoveragePolicy,
pub timeout: Duration,
}
}73. Linux Tests
Run on Linux-compatible Swift runner.
74. macOS Tests
Use macOS runner.
75. Simulator Tests
Schedule onto:
macOS runner
+
required simulator runtime/device profile
76. Physical Device Tests
Use Forgeyard device lab.
Runner/device capability includes:
platform
OS version
architecture
device family
signing/development entitlement state
77. UI Tests
Store:
screenshots
logs
video where available
test result bundles
crash logs
as CAS artifacts.
78. Test Sharding
Shard by:
test bundle
test class/suite
device
simulator
historical duration
according to test framework capabilities.
79. Flaky Tests
Retries remain visible.
Passing retry does not erase original failure.
80. Code Coverage
Support compiler/Xcode/LLVM coverage paths.
Coverage data is verification evidence.
81. Coverage Identity
Include:
Swift toolchain
test target
instrumentation settings
source mapping
82. Static Analysis
Potential:
Swift compiler warnings
SwiftLint adapter
custom analyzers
Clang analysis for mixed code
83. Formatting
Adapters:
swift-format
SwiftFormat
CI should verify, not rewrite source silently.
84. Documentation
Support:
DocC
SwiftPM documentation workflows
as separate artifact generation.
85. DocC Identity
Track:
toolchain
package/module
catalog/source
compiler/module graph
86. API Compatibility
Optional release gate for libraries:
public API diff
ABI compatibility
module interface diff
where tooling allows.
87. Library Evolution
If a library uses stable ABI/library-evolution settings, those compiler options are explicit derivation inputs.
88. Module Interfaces
Generated .swiftinterface and related module artifacts are separate outputs where applicable.
89. Static Library
Output includes:
archive
module artifacts
headers/module maps if exposing C/ObjC interface
90. Dynamic Library
Validate runtime closure.
91. Framework
Framework packaging may contain:
binary
Swift modules
headers
resources
Info.plist
All content is hashed.
92. XCFramework
First-class packaging target for distributing multiple platform/architecture variants.
93. XCFramework Derivation
verified platform slices
↓
slice metadata validation
↓
XCFramework assembly
↓
content digest
Do not rebuild slices during assembly.
94. XCFramework Slice Model
#![allow(unused)]
fn main() {
pub struct XcframeworkSlice {
pub platform: SwiftPlatform,
pub architecture: Architecture,
pub simulator: bool,
pub artifact: StoreObjectId,
}
}95. XCFramework Validation
Verify:
expected platforms
architectures
module interfaces
headers
binary identity
96. Swift Package Binary Distribution
If distributing binary targets:
binary artifact
checksum
manifest metadata
are release outputs.
97. Application Bundle
Apple app bundle contains:
executable
frameworks
resources
Info.plist
entitlements relationship
embedded Swift runtime/frameworks as applicable
98. Unsigned Build Core
Forgeyard should separate:
unsigned/pre-signing application artifact
from:
signed deliverable
whenever Apple tooling permits a meaningful separation.
99. Signing Identity
Signing material is late-bound:
certificate
private key
team identity
provisioning profile
not source derivation identity.
100. Signing Model
UnsignedArtifactDigest
↓
SigningOperation
↓
SignedArtifactDigest
Both are recorded.
101. Entitlements
Entitlements affect signed runtime behavior and often bundle/signature output.
Treat entitlements file/configuration as explicit release/signing input.
102. Provisioning Profiles
Provisioning profile is signing/deployment input.
Store metadata/digest under protected secret/artifact policy as appropriate.
103. Secret Storage
Signing keys/certificates use Forgeyard SecretProvider.
Never normal CAS/plain logs.
104. Notarization
macOS distribution may require notarization.
Model as post-build release effect:
signed package
↓
notarization submission
↓
notarization result
↓
stapled/final artifact where applicable
105. Notarization Is Not Build Identity
It is provenance/release state.
The pre-notarized artifact remains independently identifiable.
106. App Store Packaging
Apple application publishing uses verified prebuilt artifacts.
Forgeyard never recompiles during App Store upload.
107. App Store Adapter
Flow:
verified signed artifact
↓
approval
↓
upload
↓
store processing state
108. macOS Distribution
Potential:
.app
.pkg
.dmg
zip
Signing/notarization policy depends on format.
109. Linux Swift Server Deployment
Potential:
binary + runtime libs
tar.zst
deb/rpm
OCI
110. OCI
Use immutable base image digest.
Prefer:
build verified Swift binary
↓
assemble image
rather than rebuilding inside Docker stage.
111. Swift Runtime Libraries
For Linux/deployment, runtime Swift libraries must be explicit runtime closure.
112. Reproducibility
Same derivation:
Runner A -> Output X
Runner B -> Output Y
Compare actual content according to target policy.
113. Common Nondeterminism Sources
absolute build paths
debug information
archive timestamps
generated metadata
Xcode build metadata
asset processing
plugin-generated files
macro behavior
native linker metadata
codesigning
notarization
114. Stable Build Paths
Use stable virtual roots where possible.
Native C/C++ prefix mapping comes from Forgeyard native subsystem.
115. Debug Info
May contain physical build paths.
Apply target/toolchain-specific remapping where supported.
116. Release vs Debug
Reproducibility policy focuses on release artifacts first.
Debug symbol artifacts can be compared separately.
117. Independent Reproducer
For Linux:
separate Linux runner
For Apple:
separate macOS runner with same Xcode/SDK contract
118. Apple Reproducer Constraint
“Different machine” does not mean different Xcode/SDK.
For bit comparison, toolchain/platform contract must match.
119. Reproduction Mismatch
Quarantine.
Diff:
binary
Swift module artifacts
resources
framework contents
XCFramework slices
Info.plist
generated source
native libraries
debug sections
120. Signing/Reproduction Boundary
Recommended:
reproduce unsigned/pre-signing artifact
then sign
when platform pipeline permits.
If signing determinism is required/possible, compare signed outputs separately.
121. Cache Layers
SwiftPM cache
.build
Xcode DerivedData
module cache
Clang module cache
plugin cache
macro build cache
Forgeyard action cache
Forgeyard CAS
All ecosystem caches are acceleration only.
122. Module Cache
Swift/Clang module caches are highly toolchain/SDK-sensitive.
Namespace by:
SwiftToolchainId
SDK
target
compiler flags
module graph
123. Incremental Compilation
Mutable acceleration.
Release reproduction uses clean build path.
124. Remote Execution
Useful boundaries:
Linux Swift build
package target builds
tests
analysis/docs
Apple target build jobs
simulator test shards
XCFramework slice builds
Avoid reimplementing compiler internal incremental dependency engine.
125. Scheduler Capabilities
#![allow(unused)]
fn main() {
pub struct SwiftRunnerCapabilities {
pub swift_toolchains: Vec<SwiftToolchainId>,
pub xcodes: Vec<XcodeId>,
pub apple_sdks: Vec<AppleSdkId>,
pub native_toolchains: Vec<CppToolchainId>,
pub targets: Vec<SwiftTargetCapability>,
pub simulators: Vec<SimulatorCapability>,
pub devices: Vec<DeviceCapability>,
pub sandbox: SandboxCapabilities,
}
}126. Hard Placement Constraints
Filter:
Swift toolchain
target OS
architecture
Xcode requirement
Apple SDK
deployment target compatibility
simulator/device runtime
native C/C++ requirement
signing trust tier
memory
127. Scheduler Scoring
Score:
SwiftPM dependency locality
toolchain locality
Xcode/SDK locality
native closure locality
DerivedData/cache warmth
device availability
queue delay
resource headroom
128. Apple Runner Pools
Recommended:
macos-swift-build
ios-simulator
ios-device
watchos-simulator
tvos-simulator
visionos-simulator
macos-signing
129. Linux Runner Pools
linux-swift-x86_64
linux-swift-arm64
with explicit libc/sysroot contracts.
130. macOS Capacity Optimization
Before consuming scarce macOS capacity, run:
manifest validation
dependency resolution
format/static analysis where platform-neutral
Linux tests where applicable
when project semantics allow.
131. Test Device Scheduling
Device tests require leases.
#![allow(unused)]
fn main() {
pub struct DeviceLease {
pub lease_id: LeaseId,
pub device_id: DeviceId,
pub job_id: JobId,
pub expires_at: Timestamp,
}
}132. Device Cleanup
After test:
remove app
reset test data
collect logs
release device
according to pool policy.
133. SwiftPM Plugin Permissions
If a plugin requires additional permissions/effects, Forgeyard policy surfaces and audits them.
134. Macro/Plugin Risk Labels
Dependency graph flags:
macro target
build-tool plugin
command plugin
binary target
system-library target
C/C++ interop
135. Supply-Chain Policy
Potential:
Package.resolved required for applications
Git dependencies locked
binary target checksums required
plugins surfaced
macros surfaced
system libraries explicitly allowed
untrusted sources denied
revoked dependencies denied
136. Dependency Trust
Unverified
RevisionVerified
ChecksumVerified
OrganizationApproved
Revoked
137. Lock Diff
Semantic example:
swift-argument-parser 1.x -> 2.x
2 transitive packages changed
1 macro package added
1 binary target added
minimum macOS target changed
138. SBOM
Combine:
SwiftPM dependency graph
binary targets
system/native libraries
Apple frameworks where policy wants platform dependency evidence
Swift runtime closure
139. Provenance
Record:
source digest
Package.swift digest
Package.resolved digest
SwiftToolchainId
SwiftPM identity
plugin graph
macro graph
target
architecture
deployment target
XcodeId
AppleSdkId
native dependency closure
build configuration
output digest
runner
sandbox policy
signing/notarization relationship
140. Build Once, Promote Many
source
↓
unsigned artifact X
↓
test/reproduce X
↓
sign X
↓
package/publish
No source recompilation during promotion.
141. Swift Package Publishing
For source packages:
verified source tag/revision
Package.swift validation
tests
API checks
provenance
Publishing often means Git release/tag rather than central package upload; Forgeyard models it as release metadata/promotion.
142. Binary Swift Package Publishing
If package references XCFramework/binary artifact:
build verified XCFramework
↓
compute checksum
↓
publish immutable artifact
↓
update package metadata in separate controlled release
143. CLI
Recommended:
forgeyard swift detect
forgeyard swift lock
forgeyard swift fetch
forgeyard swift graph
forgeyard swift build
forgeyard swift test
forgeyard swift analyze
forgeyard swift format-check
forgeyard swift coverage
forgeyard swift docs
forgeyard swift reproduce
forgeyard swift package
forgeyard swift xcframework
forgeyard swift explain
forgeyard swift explain-rebuild
forgeyard swift toolchain
forgeyard swift plugins
forgeyard swift macros
forgeyard swift native
forgeyard apple xcode
forgeyard apple sdk
forgeyard apple simulator
forgeyard apple device
forgeyard apple sign
forgeyard apple notarize
forgeyard apple publish
144. Explain Build
Show:
Swift toolchain
SwiftPM
Package.resolved
dependency graph
plugin graph
macro graph
target
architecture
deployment target
Xcode/SDK
native closure
compiler settings
cache state
145. Explain Rebuild
Examples:
Swift toolchain changed
Package.resolved changed
macro implementation changed
plugin changed
binary target changed
Xcode changed
Apple SDK changed
deployment target changed
Clang/native library changed
146. Dioxus UI
Dedicated Swift panels:
Swift toolchain
SwiftPM package graph
Plugins/macros
Native interop
Targets
Linux
Xcode/Apple SDK
Simulators/devices
Tests
Coverage
Docs
Reproducibility
XCFrameworks
Signing
Notarization
Publishing
147. Toolchain UI
Display:
Swift version
Swift compiler digest
SwiftPM
Clang
platform
trust
148. Package Graph UI
Show:
package
revision/version
source
digest
products
targets
plugins
macros
binary targets
system libraries
149. Apple Target UI
Show:
platform
architecture
simulator/device
deployment target
Xcode
SDK
signing state
150. XCFramework UI
Display slices:
platform
architecture
simulator/device
artifact digest
module compatibility
151. Signing UI
Display only non-secret metadata:
team
certificate identifier/fingerprint
profile identifier
entitlements digest
signed artifact digest
Never private key material.
152. Failure Classification
#![allow(unused)]
fn main() {
pub enum SwiftFailure {
DetectionFailure,
ToolchainFailure,
PackageResolutionFailure,
LockFailure,
BinaryTargetFailure,
PluginFailure,
MacroFailure,
NativeInteropFailure,
CompileFailure,
LinkFailure,
TestFailure,
CoverageFailure,
AnalysisFailure,
DocumentationFailure,
AppleSdkFailure,
XcodeFailure,
SimulatorFailure,
DeviceFailure,
SigningFailure,
NotarizationFailure,
PackagingFailure,
PublishingFailure,
ReproducibilityFailure,
}
}153. Hermeticity Violation Example
Swift native dependency violation
target:
ServerCore
attempted library:
/usr/local/lib/libfoo.so
reason:
outside declared native closure
154. Xcode Drift Example
Apple toolchain mismatch
locked:
XcodeId A
AppleSdkId X
runner:
XcodeId B
AppleSdkId Y
action:
build refused
155. Plugin Violation Example
SwiftPM plugin network access denied
plugin:
CodeGeneratorPlugin
policy:
hermetic release build
156. Development Environment
forgeyard swift dev
provides:
locked Swift toolchain
SwiftPM graph
native dependencies
analysis/docs tools
On macOS it can additionally expose controlled Xcode/SDK metadata.
157. IDE Integration
Expose:
Swift toolchain
package graph
target
Xcode project/workspace metadata
compile commands/native metadata where useful
IDE state remains non-authoritative.
158. Local Mode
On Linux:
SwiftPM resolve/fetch
build
test
docs
package
On macOS:
same +
Apple targets available locally
according to installed/managed toolchain contracts.
159. Distributed Mode
daemon
↓
Swift target job
↓
compatible runner
↓
toolchain + package closure + SDK/native closure
↓
build/test
↓
CAS
160. Enterprise Mode
Adds:
approved Swift toolchain mirror
package source mirror/cache
macOS build farm
simulator/device farm
signing service
notarization automation
signed lock approvals
OIDC/RBAC
multi-region CAS
161. Air-Gapped Linux Build
Bundle:
source
Swift toolchain
SwiftPM dependency closure
binary targets
native sysroot/libs
lock graph
162. Controlled Apple Build
Apple SDK/Xcode licensing/platform constraints mean an “air-gapped” Apple build still requires properly provisioned macOS/Xcode infrastructure.
Forgeyard can make dependency/network state offline while respecting platform/toolchain requirements.
163. Signing Service Boundary
Recommended trust separation:
general build runners
↓
verified unsigned artifact
↓
restricted signing worker/service
Signing credentials never exposed to ordinary runners.
164. Notarization Worker
Separate capability:
apple-notarization
with network access only for notarization service interaction.
165. Release Promotion States
Built
Tested
Reproduced
UnsignedApproved
Signed
Notarized
Published
Promoted
Not all states apply to every target.
166. Reference Linux Swift PR Pipeline
detect
↓
lock verification
↓
format check
↓
build
↓
tests
↓
analysis
↓
docs
167. Reference Apple PR Pipeline
manifest/lock checks
↓
platform-neutral validation
↓
macOS build
↓
simulator tests
↓
native interop checks
168. Reference Library Release Pipeline
clean source
↓
locked toolchain
↓
locked package graph
↓
offline hermetic build
↓
tests/API checks
↓
build platform slices
↓
independent reproduction
↓
assemble XCFramework/package
↓
SBOM/provenance
↓
publish immutable artifact
169. Reference macOS App Release Pipeline
clean source
↓
locked Swift/Xcode/SDK
↓
locked dependencies
↓
offline/controlled build
↓
tests
↓
unsigned app artifact
↓
independent reproduction
↓
codesign
↓
package
↓
notarize
↓
SBOM/provenance
↓
publish/promote
170. Reference iOS Release Pipeline
clean source
↓
locked Swift/Xcode/iOS SDK
↓
locked packages/plugins
↓
build
↓
simulator/device tests
↓
verified app/archive
↓
sign/export
↓
provenance
↓
App Store distribution
171. Production Defaults
Recommended:
locked Swift toolchain
Package.resolved enforced for application releases
dependency revisions/content verified
offline build after fetch
isolated HOME/cache
plugins/macros surfaced
plugin network denied
native dependencies locked
explicit target
explicit architecture
explicit deployment target
explicit Xcode/SDK
clean release build
independent reproduction
late signing
172. Development Defaults
May allow:
incremental build
warm SwiftPM cache
DerivedData reuse
local simulators/devices
dirty source
with visible non-release status.
173. Error-Prone Behaviors to Prevent
Forgeyard should detect/reject:
floating Swift toolchain selector
Package.resolved mutation during release build
mutable Git dependency
path dependency outside source snapshot
ambient SwiftPM cache dependence
plugin network access
macro/plugin toolchain mismatch
host pkg-config leakage
host C/C++ library leakage
ambient DEVELOPER_DIR
Xcode drift
Apple SDK drift
deployment target drift
simulator/device confusion
unsigned/signed artifact identity confusion
signing key exposure
rebuild during publishing
174. Implementation Phase 1 — Domain + Detection
Implement:
SwiftProjectSpec
Package.swift detection
Package.resolved detection
product/target model
Swift toolchain model
plugin/macro detection
native target detection
Exit:
Forgeyard accurately describes ordinary SwiftPM packages.
175. Phase 2 — Linux Toolchain Locking
Implement:
SwiftToolchainId
SwiftPM identity
Clang identity
Swift runtime closure
176. Phase 3 — SwiftPM Resolution
Implement:
Git/path dependencies
Package.resolved
binary targets
package graph
offline materialization
Exit:
Linux Swift package builds offline.
177. Phase 4 — Plugins + Macros
Implement:
plugin graph
macro graph
sandbox policy
generated source/output capture
178. Phase 5 — Native Interop
Integrate:
C
Objective-C where applicable
C++
pkg-config
module maps
C/C++ runtime linkage
179. Phase 6 — Tests/Analysis/Docs
Implement:
XCTest
Swift Testing
coverage
format/lint adapters
DocC
180. Phase 7 — macOS/Xcode
Implement:
XcodeId
AppleSdkId
DEVELOPER_DIR control
deployment targets
Xcode build adapter
181. Phase 8 — iOS/Other Apple Platforms
Implement:
iOS
watchOS
tvOS
visionOS
simulator/device target contracts
182. Phase 9 — XCFramework
Implement:
slice builds
slice validation
assembly
checksums
binary package publishing
183. Phase 10 — Signing/Notarization
Implement:
restricted signing worker
profiles/certificates
entitlements
notarization
provenance linkage
184. Phase 11 — Reproducibility
Implement:
clean builds
stable path policies
binary/framework diffs
independent Linux/macOS rebuilders
unsigned artifact comparison
185. Phase 12 — Device/Enterprise
Implement:
simulator/device pools
signing service
Apple build farm
package mirrors
multi-region CAS
air-gap/dependency-offline workflows
186. Acceptance Tests
- Remove host Swift install on Linux: locked toolchain build succeeds.
- Change ambient HOME SwiftPM state: strict build unchanged.
- Disable network after fetch: package builds.
- Change Package.resolved: graph identity changes.
- Git branch moves: locked revision remains fixed or verification fails.
- Path dependency outside source snapshot: strict build rejects.
- Macro implementation changes: derivation changes.
- Plugin attempts network: sandbox rejects.
- Native library resolves from
/usr/local: strict build rejects. - Swift toolchain changes: derivation changes.
- Clang changes for native interop: derivation changes.
- Xcode changes: Apple derivation changes.
- Apple SDK changes: derivation changes.
- Deployment target changes: derivation changes.
- Simulator/device target switch changes identity.
- Independent Linux runner reproduces release artifact.
- Independent macOS runner reproduces unsigned Apple artifact where supported.
- Reproducer mismatch quarantines release.
- Signing key never enters build runner/CAS.
- Publishing promotes exact verified artifact.
187. Production Readiness Gates
Do not call Swift support production-ready until:
Swift toolchain identity is stable
SwiftPM dependency locking works
offline builds work
binary targets are verified
plugins/macros are modeled
native C/C++ interop is hermetic
Linux runtime closure works
Xcode/Apple SDK identity is explicit
deployment targets are enforced
simulator/device targets are distinct
XCTest/Swift Testing work
XCFramework assembly is deterministic enough for release
signing is isolated
notarization is modeled
reproducibility detects mismatches
publishing never rebuilds
188. Architectural Invariants
- Swift version string alone is not toolchain identity.
- SwiftPM remains semantic authority.
- Locked dependency revisions/content are explicit inputs.
- Strict builds do not fetch dependencies from network.
- Host SwiftPM cache is not source of truth.
- Path dependencies never escape source/store boundaries.
- Binary targets are checksum/content verified.
- SwiftPM plugins are executable build dependencies.
- Swift macros are executable compile-time dependencies.
- Native C/ObjC/C++ interop introduces explicit Clang/native closure.
- Host and target are distinguished where plugins/macros/native tools require it.
- Xcode selection is explicit.
- Apple SDK identity is explicit.
- Deployment target is explicit.
- Simulator and device are distinct targets.
- Incremental/DerivedData/module caches are acceleration only.
- Unsigned and signed artifact identities are distinct.
- Signing secrets are isolated from build runners.
- Notarization is a release effect, not source build identity.
- XCFramework assembly uses already-verified slices.
- Reproducibility compares actual artifacts.
- Publishing/promoting never recompiles.
- Apple builds run on appropriate Apple infrastructure.
- Forgeyard never pretends Linux can substitute for final Apple SDK/signing work.
- Correctness takes priority over aggressive remote-execution granularity.
189. Final Target Architecture
Swift Project
│
▼
Forgeyard Swift Detector
│
▼
SwiftProjectSpec
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
Toolchain Resolver SwiftPM Resolver Platform Resolver
│ │ │
├──────────────┐ │ ┌─────────────┤
▼ ▼ ▼ ▼ ▼
Plugins Macros Native Xcode/SDK
│ │ │ │
└──────────────┴────────────┼─────────────┘
▼
Immutable Swift Lock
│
▼
Build/Test Graph
│
▼
Forgeyard Scheduler
│
▼
Swift Runner
│
┌──────────────┼──────────────┐
▼ ▼ ▼
swiftc Plugins/Macros Clang
│ │ │
└──────────────┼──────────────┘
▼
Tests / Coverage / Docs
│
▼
Content-Addressed Artifact
│
▼
Independent Reproducer
│
▼
Package / Framework / XCFramework
│
▼
Signing / Notarization
│
▼
SBOM / Provenance / Publish
190. Final Architectural Position
For portable/Linux Swift:
Source snapshot
+
Swift toolchain
+
SwiftPM
+
Package.swift
+
Package.resolved/resolved dependency graph
+
target
+
Swift plugins
+
Swift macros
+
resources
+
C/C++ native closure where used
+
controlled environment
+
hermetic sandbox
=
Swift derivation
For Apple Swift:
Swift derivation
+
Xcode
+
Apple SDK
+
platform
+
architecture
+
simulator/device distinction
+
deployment target
+
Apple frameworks/native interop
=
Apple Swift derivation
Signing remains separate:
Apple Swift derivation
↓
unsigned/pre-signing artifact
↓
signing identity + profile + entitlements
↓
signed artifact
↓
optional notarization
A trustworthy Swift release requires:
Derivation
↓
offline hermetic SwiftPM realization
↓
plugins/macros/native build
↓
tests / analysis / coverage / docs
↓
actual artifact digest
↓
independent reproduction
↓
framework/app/XCFramework packaging
↓
late signing/notarization
↓
SBOM + provenance
↓
promotion/publishing of identical verified artifacts
This gives Forgeyard a Swift architecture that works for both server-side Swift and Apple’s tightly coupled platform ecosystem, while preventing SwiftPM cache state, floating Git dependencies, plugins/macros, native interop, Xcode drift, Apple SDK drift, deployment-target differences, and signing credentials from becoming hidden CI inputs.
Appendix A — Recommended Swift Release Policy
(
swift_release_policy: (
source: (
dirty_tree: Denied,
),
toolchain: (
locked: Required,
),
dependencies: (
resolved_graph_locked: RequiredForApplications,
source_content_verified: Required,
network_during_build: Denied,
external_path_dependency: Denied,
binary_target_checksum: Required,
),
build_time_code: (
plugins_locked: Required,
macros_locked: Required,
network: Denied,
),
native: (
native_toolchain_locked: RequiredWhenPresent,
runtime_closure_validation: RequiredWhenPresent,
),
apple: (
xcode_explicit: RequiredWhenAppleTarget,
sdk_explicit: RequiredWhenAppleTarget,
deployment_target_explicit: RequiredWhenAppleTarget,
simulator_device_distinct: Required,
),
signing: (
late_bound: Required,
build_runner_key_access: Denied,
),
reproducibility: (
independent_rebuilds: 1,
compare_unsigned_core_where_possible: true,
),
release: (
sbom: Required,
provenance: Required,
rebuild_on_promotion: Denied,
),
),
)
Appendix B — Example Linux Swift Configuration
swift: (
toolchain: Locked("swift-linux"),
package: (
resolved: "Package.resolved",
network_during_build: Denied,
),
target: (
platform: Linux,
architecture: X86_64,
),
testing: (
unit: Required,
coverage: Recommended,
),
reproducibility: (
independent_rebuilds: 1,
),
)
Appendix C — Example macOS Swift Configuration
swift: (
toolchain: Locked("swift-xcode"),
target: (
platform: MacOS,
architecture: Arm64,
deployment_target: "explicit",
xcode: Locked("xcode"),
sdk: Locked("macos-sdk"),
),
dependencies: (
network_during_build: Denied,
),
reproducibility: (
compare_unsigned_core_where_possible: true,
independent_rebuilds: 1,
),
)
Appendix D — Example XCFramework Configuration
swift: (
product: Xcframework(
slices: [
(
platform: IOS,
architecture: Arm64,
simulator: false,
),
(
platform: IOS,
architecture: Arm64,
simulator: true,
),
(
platform: MacOS,
architecture: Arm64,
simulator: false,
),
],
),
)
Appendix E — First-Class Swift Tooling Matrix
| Area | First-class |
|---|---|
| Language | Swift |
| Build/dependency | Swift Package Manager |
| Dependency state | Package.swift, Package.resolved |
| Build-time code | SwiftPM plugins, Swift macros |
| Native interop | C, Objective-C, C++ via Clang/Forgeyard C++ |
| Linux | Swift toolchain + libc/native closure |
| macOS | Xcode/Apple SDK |
| iOS | Xcode/iOS SDK, simulator/device |
| watchOS | Xcode/watchOS SDK |
| tvOS | Xcode/tvOS SDK |
| visionOS | Xcode/visionOS SDK |
| Testing | XCTest, Swift Testing |
| Coverage | LLVM/Xcode coverage adapters |
| Formatting | swift-format / SwiftFormat adapters |
| Analysis | compiler warnings, SwiftLint adapter |
| Docs | DocC |
| Libraries | static/dynamic libraries, frameworks |
| Multi-platform distribution | XCFramework |
| Apps | Apple app bundles |
| Signing | codesign/provisioning via restricted worker |
| Notarization | macOS release effect |
| Distribution | App Store/enterprise/download adapters |
| Reproducibility | clean hermetic build + independent unsigned artifact reproduction |
Appendix F — Upstream Integration Principles
Forgeyard should preserve Swift and Apple-platform semantics rather than inventing incompatible substitutes:
- Swift Package Manager remains the authority for package/target/dependency semantics.
Package.resolvedis treated as application/release dependency-resolution evidence, while Forgeyard adds immutable source-content and toolchain identity around it.- SwiftPM plugins and Swift macros are executable build-time/compile-time dependencies and therefore must be surfaced, locked, and isolated.
- C/Objective-C/C++ interoperability depends on Clang, headers, module maps, native libraries, and target SDKs, so these are explicit native closure inputs.
- Apple builds depend on Xcode and Apple SDK contracts that cannot be treated as ordinary portable host tools.
- Simulator and physical-device targets have different platform/runtime identities.
- XCFramework packaging combines already-built platform/architecture slices and must never hide rebuilding.
- Codesigning, provisioning, and notarization are release effects layered on verified build outputs rather than excuses to make the core build mutable.