sunnypilot v2026.002.000

version: sunnypilot v2026.002.000 (staging)
date: 2026-07-21T07:44:02
master commit: 2c334ede443d7391d27575af8c854a095ba702a8

openpilot/sunnypilot/models/README.md

@@ -0,0 +1,63 @@
+# Model Selector Version Compatibility
+
+This document explains the version compatibility mechanism used by the Model Selector system, and the rationale behind certain version constraints and JSON file management strategies.
+
+## Overview
+
+The Model Selector is responsible for selecting and validating model bundles based on their metadata and version constraints. Each model bundle is distributed via a JSON file and includes a `minimumSelectorVersion` field indicating the minimum selector version required to load it.
+
+To ensure robust compatibility and prevent mismatches between model expectations and selector capabilities, the selector enforces two version boundaries:
+
+* **`REQUIRED_MIN_SELECTOR_VERSION`**: the oldest selector version we support.
+* **`CURRENT_SELECTOR_VERSION`**: the current version of the selector logic.
+
+## Version Compatibility Check
+
+A model bundle is considered compatible if:
+
+```python
+REQUIRED_MIN_SELECTOR_VERSION <= bundle["minimumSelectorVersion"] <= CURRENT_SELECTOR_VERSION
+```
+
+This ensures:
+
+* **Old bundles are rejected** if they rely on deprecated selector behavior.
+* **Future bundles are ignored** if they expect logic that the current selector doesn't yet implement.
+
+## Handling Breaking Changes
+
+When a deep change in selector behavior requires *all* models to be recompiled (e.g., due to a major architectural update), we:
+
+1. **Create a new JSON file** (e.g., from `models_v4.json` to `models_v5.json`).
+2. **Assign updated `minimumSelectorVersion` values** in the new bundles.
+
+This allows older selector versions to continue using the previous JSON file, while newer versions point to the new one, preventing cross-contamination.
+
+## Why `REQUIRED_MIN_SELECTOR_VERSION` Still Matters
+
+Despite using new JSON files to isolate breaking changes, `REQUIRED_MIN_SELECTOR_VERSION` plays a critical role:
+
+### 1. **Cached Bundle Validation**
+
+Model bundles are cached locally (e.g., in-memory or on disk). A user might have previously loaded a now-invalid bundle from an older JSON file.
+
+`REQUIRED_MIN_SELECTOR_VERSION` prevents the selector from reloading or trusting that stale cached bundle, even if the original JSON is gone.
+
+### 2. **Explicit Deprecation Boundary**
+
+By raising `REQUIRED_MIN_SELECTOR_VERSION`, we declare older bundles officially unsupported, even if they technically still exist in a legacy JSON file.
+
+### 3. **Avoiding Race Conditions**
+
+Some clients may have intermittent access to updated JSONs. The runtime check ensures version compatibility is enforced independently of external file state.
+
+## Summary
+
+| Component                       | Purpose                                                               |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `minimumSelectorVersion`        | Declares the minimum selector version required to load a model bundle |
+| `REQUIRED_MIN_SELECTOR_VERSION` | Prevents loading bundles that are too old (e.g., from stale cache)    |
+| `CURRENT_SELECTOR_VERSION`      | Prevents loading bundles that are too new or forward-incompatible     |
+| JSON file renaming              | Isolates bundles by selector generation to handle full recompiles     |
+
+This layered strategy ensures safe evolution of the model selection system while maintaining backward compatibility and runtime protection against stale or incompatible bundles.