onepilot/sunnypilot/models

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:

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.