fix(build): check-toolchain rejects SDK < 27 with a clear message (#520)

[Arthur-Ficial]

Draft PR - needs @franzenzenhofer review and local test run before merging.

Fixes #520.

Root cause

Since v1.15.0 the sources UsageAccounting.swift and VisionSupport.swift (and since the unreleased work on main, ToolCallingSupport.swift and TypedErrorSupport.swift too) use macOS 27-only FoundationModels types (LanguageModelSession.Usage, LanguageModelSession.Response, LanguageModelCapabilities, etc.) behind runtime #available gates but without compile-time SDK guards. The check-toolchain Makefile target still accepted SDK >= 26.4, so make build / make install with a 26.x SDK fell through to swift build, which then produced cryptic compiler errors about missing types.

The fix

Option 1 from the issue: raise the check-toolchain SDK floor from 26.4 to 27. The guard is now simply [ "$major" -lt 27 ] instead of the compound 26.4 check. The error message names the cause (macOS 27 FoundationModels API used at compile time), lists the affected source files, and offers brew install apfel as the no-build alternative. docs/install.md troubleshooting sections updated to match.

Test coverage

• Added Tests/integration/test_build_info.py::test_check_toolchain_requires_sdk_27 to lock the SDK floor in place - it statically checks the Makefile recipe rejects SDK < 27 and does not reference the old 26.4 threshold.
• Existing test_build_target_does_not_depend_on_generate_build_info and the swift build/run --build-system native tests still cover their respective Makefile hygiene.

What I verified (static only)

• Makefile check-toolchain recipe now contains -lt 27 and no 26.4 references.
• docs/install.md "Verify your toolchain" and "Troubleshooting build errors" sections updated to SDK 27.
• docs/install.md line 37 (the "Build from source" intro) was already updated on main to say "macOS 27 SDK" - no change needed there.
• CHANGELOG [Unreleased] ### Fixed entry added.
• Diff limited to Makefile, Tests/integration/test_build_info.py, docs/install.md, CHANGELOG.md - no touches to release infrastructure, guardrails, CI, dependencies, .version, or BuildInfo.swift.
• Swift 6 concurrency: no Swift code changed.

What I did NOT verify

• Functional correctness. This needs make test on a Mac with Apple Intelligence. I cannot run FoundationModels code. If the fix does not actually resolve the reported behaviour, that is on me to refine - ping me in a review comment.

Follow-up items (not in this PR)

• README.md line 41 still says "macOS 26.4 SDK" for building from source - should be updated to 27.
• docs/brew-install.md line 19 says "macOS 26.4 or newer" - this is about the runtime requirement (not the build SDK) and may be a separate issue since the runtime floor is macOS 26.0.

Anything that seemed suspicious

Nothing - straightforward bug filed by our own account from the v1.16.0 pre-release review.

---

cc @franzenzenhofer - draft stays draft until you review, test locally, and mark ready.

Generated by the apfel bug-solver routine.

🤖 Generated with Claude Code

https://claude.ai/code/session_019ZCGi94GGTFqn8zQaHW32p

---

Generated by Claude Code

[Arthur-Ficial]

The build-and-test CI failure is not this PR's - it's the pre-existing issue that #520 is about. The GitHub Actions macos-26 runner has SDK 26.5, which has been failing to build since v1.14.0 (the commit that added UsageAccounting.swift). The last 5 pushes to main all have conclusion: failure for the same reason.

This PR makes the failure clearer (a one-line check-toolchain error instead of cryptic compiler output), but the runner still can't build until either the runner gets upgraded to the 27 SDK or the CI workflow is updated to select a macOS 27 runner image.

changelog-gate passed. apfelcore-public-api is still running (no ApfelCore changes in this diff, so it should pass).

No fix to port here - the underlying runner SDK version is an infrastructure issue outside this PR's scope.

---

Generated by Claude Code