[Build] Preflight and repair invalid SwiftPM repository caches

[stephenlclarke]

Defect

A clean linked worktree can enter a nominally cached SwiftPM resolve with missing maintenance.lock metadata. SwiftPM then emits repeated skipping cache warnings and refetches/recomputes the dependency graph instead of failing fast or repairing the cache once.

Evidence

On 6 September 2026, swift test --filter EngineSocketGrantTests reported the missing lock for many packages. aws-sdk-swift alone consumed 225.72 seconds before project compilation began. The complete focused command took 420.33 seconds.

Required outcome

• Validate the shared repository cache before a timed build/test starts.
• Repair or quarantine a cache with missing lock/metadata deterministically.
• Reuse one immutable dependency checkout across linked worktrees when the package fingerprint matches.
• Retain timing and cache-hit evidence in the recoverable build trace.

Parent programme: stephenlclarke/container-compose#324.

[stephenlclarke]

Fresh evidence from the Compose deterministic-build slice on 6 September 2026:

An isolated Swift package root was created to keep a local dependency edit away from the tracked Compose lockfile. SwiftPM immediately reported missing maintenance.lock metadata for cached repositories including containerization, swift-nio-ssl, container-engine-api, swift-docc-symbolkit, zstd, swift-certificates, swift-log, swift-system, async-http-client, swift-http-types, swift-crypto, swift-nio, and swift-collections.

The supposedly local graph operation ran for more than 30 seconds and created 390 MiB of replacement state before it was stopped. No product compilation had begun. The isolated state was removed and the tracked Compose checkout remained unchanged.

This confirms that creating a fresh package root is not a viable lock-isolation strategy until the shared SwiftPM cache validates its metadata and fails or repairs before dependency resolution.