James Vecellio-Grant
7c6d887187
* modeld_v2: dynamify temporal buffer management. * skip redundant reshaping and flattening. * simplify MHP checks for lead and plan * modeld_v2: add unit tests for buffer logic and refactor index mapping * Let’s possibly fail a test :) * Update test_buffer_logic_inspect.py * Update test_buffer_logic_inspect.py * modeld_v2: better temporal mapping for non-split * Bump to 10 I guess * Downgrade CURRENT_SELECTOR_VERSION to 9 * red diff ya know? * add dynamic buffer update tests and compare against legacy logic. Cover modelState.init and modelState.run * send * Revert "send" This reverts commit 9e6c95fbfde134eeba952da6eef012baa0396fa0. * format --------- Co-authored-by: Jason Wen <haibin.wen3@gmail.com>
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:
- Create a new JSON file (e.g., from
models_v4.jsontomodels_v5.json). - Assign updated
minimumSelectorVersionvalues 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.