fix(swift-ios): prevent approved device build downgrades

[saphid]

Summary

Makes physical-device installs require a positive build number newer than the installed build. Uses a Swift JSON resolver instead of jq, has an explicit recovery override for device-query failures, and wires validation into native CI.

Verification

• apps/swift-ios/Scripts/ci-test.sh — 218 tests passed; validate-device-build-number.test.sh passed
• Fresh independent Claude Opus 5 high review completed; all actionable findings were addressed and the final repair review found no blockers.
• Simulator visual evidence will be attached before marking this PR ready for review.

Scope

Targets the active native SwiftUI owner branch (#5178).

Note

Prevent approved device build downgrades in iOS device install script

• install-device.sh now requires T3_SWIFT_BUILD_NUMBER to be set and validates it is a positive integer greater than the build already installed on the target device.
• Queries the device for installed apps via xcrun devicectl device info apps, then resolves the installed build number using the new resolve-installed-build-number.swift utility.
• Build comparison logic lives in validate-device-build-number.sh, which warns (but accepts) when the installed build is non-numeric and errors when the requested build is not newer.
• Set T3_SWIFT_SKIP_INSTALLED_BUILD_CHECK=1 to bypass the installed-app query when the device cannot report installed apps.
• Risk: T3_SWIFT_BUILD_NUMBER is now mandatory; any existing call to install-device.sh that omits it will fail.

^{Macroscope summarized 20a57f4.}

---

Note

Low Risk
Changes are limited to developer install scripts and docs; existing automation that omitted T3_SWIFT_BUILD_NUMBER will fail until updated.

Overview
Physical device installs now require T3_SWIFT_BUILD_NUMBER and refuse to build when that value is not strictly greater than the build already on the device for the target bundle ID.

install-device.sh queries installed apps with devicectl, parses bundleVersion via new resolve-installed-build-number.swift, and runs validate-device-build-number.sh before setting CURRENT_PROJECT_VERSION. First install (no app on device) is allowed; equal or lower builds fail. T3_SWIFT_SKIP_INSTALLED_BUILD_CHECK=1 bypasses the device query when devicectl cannot list apps. README documents the required env var and escape hatch.

ci-test.sh runs validate-device-build-number.test.sh (shell tests plus Swift resolver against a JSON fixture) ahead of simulator tests.

^{Reviewed by Cursor Bugbot for commit 20a57f4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Delivery: direct
Validated against Theo commit: f98cab5
Depends on: none
Merge order: this PR only
Validation status: Mergeable; native/repository checks and current review are green. The unrelated Vercel authorization failure is a maintainer-side gate.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7e804d97-38a1-48d4-a523-e2f655b71507

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[saphid]

Integrated simulator verification completed alongside the focused script test and passing native CI. This guard is intentionally non-visual: it runs before device installation and rejects an older/equal build before mutating the target. The integrated Debug app still built, installed, paired, and launched successfully after the guard changes.

[macroscopeapp]

Approvability

Verdict: Approved 20a57f4

CI/build tooling change that adds validation to prevent iOS build downgrades during device installation. The change is well-tested with unit tests, includes an escape hatch flag, and is self-contained to build scripts with no production runtime impact.

^{You can customize Macroscope's approvability policy. Learn more.}

[t3-code]

reviewed the monotonic device build validation, installed-app parsing, failure behavior, and fixtures. no blocking issues found.

[saphid]

Closing this version while I rebuild the upstream contribution set from the latest base. Clean versions are coming soon.