Hybrid bundle: rebuild SyntaxKit from sources on toolchain mismatch

[leogdion]

Background

skitrun ships a prebuilt libSyntaxKit.{dylib,so} + SyntaxKit.swiftmodule in its release bundle (built by Docs/research/poc-step4-release.sh). Swift swiftmodules are tightly coupled to the exact compiler that built them — even patch-level Swift updates break the load (e.g., 6.3.0 ↔ 6.3.2 swiftmodules are mutually rejected).

PR #156 added stamp + detection + clear-error: skitrun reads lib/swift-version.txt on startup, compares it to swift --version, and exits cleanly with rebuild instructions on mismatch. That removes the cryptic "module compiled with Swift X" diagnostic, but users still have to manually rerun the release script every time their Swift toolchain updates.

Proposal

On detected toolchain mismatch, transparently rebuild libSyntaxKit from bundled sources against the user's local swiftc, caching by Swift-version hash. Subsequent runs in the same toolchain reuse the cached dylib; cross-toolchain switches trigger a one-time recompile (~30s–2min).

Cache layout mirrors today's helpers cache:

<syntaxkit cache>/libcache/<swiftlang-version>/
  libSyntaxKit.{dylib,so}
  SyntaxKit.swiftmodule
  ...

What this replaces

The clear-error path from PR #156 becomes the fallback when rebuild can't happen (no swiftc available, --no-rebuild set, source compile fails). The stamp file from PR #156 becomes the cache key.

Open sub-questions

• Source scope: bundle SyntaxKit sources only (~5MB) and resolve SwiftSyntax via SPM at rebuild time, or bundle SwiftSyntax sources too (~50MB) for fully offline rebuilds?
• Rebuild UX: silent / one-line stderr note (skitrun: rebuilding for swiftlang-X.Y.Z (cold; ~30s)) / progress indicator?
• Escape hatch: --no-rebuild to force-use the bundled module and exit cleanly if it can't be loaded. Useful for CI determinism.
• Cross-platform: rebuild flow needs to match POC step 7's Foundation.Process workarounds on Linux.
• CI first-rebuild cost: should the bundle ship multiple precomputed swiftmodules for common Swift versions, with rebuild as the fallback when none match?

References

• PR skit: SyntaxKit codegen CLI for v0.0.5 #156 (research POC for skitrun) — adds the stamp + detection foundation this builds on.
• Docs/research/codegen-cli-design.md §7 — open scope decisions.
• Docs/research/poc-step5-results.md — helpers cache shape (the model to follow).