Model pins

crates/vike-ml/src/pins.rs holds two constants, and its header says they live together in their own file because the version refusal has to name both and a bump has to change both in one place:

• MODEL_VERSION = "v4" — the model text format's own version= line, asserted rather than sniffed. parse_model_text refuses any other value with MlError::UnsupportedVersion.
• PINNED_LIGHTGBM_TAG = "v4.7.0" — the upstream release the trainer binary is built from, asserted at startup by crates/vike-ml/src/cli.rs's LightGbmCli::new. The doc records that upstream moved from microsoft/LightGBM to lightgbm-org/LightGBM in 4.7.0, and that v4.7.0 is tag sha 8f7036f0, released 2026-07-18.

crates/vike-ml/src/error.rs makes the refusal actionable on purpose: the UnsupportedVersion message names the version it saw, the version the walker implements, the pinned tag and the bump procedure, and its doc says a refusal an operator cannot act on is a refusal the next person widens.

What each pin proves, and what neither does

The header states the residual first because it is what a reader otherwise assumes away. MODEL_VERSION is a coarse instrument: v4 does not change when fields are added within v4. The parser tolerates unknown key=value lines silently — it must, since LightGBM already writes several the walker has no use for — so a new per-node array carrying routing meaning would be read as noise, dropped, and every prediction would be quietly wrong while the version check stayed green.

PINNED_LIGHTGBM_TAG catches "somebody put a different LightGBM on the box", which the doc calls a real and common failure — and says nothing about whether the format changed.

So the real bump proof is neither constant. It is crates/vike-ml/tests/train_infer_equality.rs, which trains a real model with the pinned binary, runs LightGBM's own task=predict over it, parses the same text with the pure-Rust walker and compares every row; its header calls the version check only a tripwire in front of it. Its eval rows deliberately include the cases a hand-written walker gets wrong — a NaN in a numerical column, a NaN in the categorical column, a negative category, a category the model never saw. crates/vike-ml/tests/real_model_golden.rs freezes one such model and its outputs into the repository so the walker is checked in the default lane, on every CI run, with no binary installed; its provenance test compares the fixture's recorded producer against the pin, which it calls the cheapest possible guard against the most expensive possible mistake.

MlError::Trainer is deliberately distinct from MlError::Backend: the first says the thing I was told to drive is not the thing I expect, an operator fault with an operator fix; the second says LightGBM ran and refused, a data or parameter fault. The Trainer message also says the other half still works — inference needs no binary at all.

Bumping the pin

The procedure is spelled where an operator meets it — crates/vike-ml/src/error.rs's UnsupportedVersion message and crates/vike-ml/src/cli.rs's refuse_version both name the steps. Move PINNED_LIGHTGBM_TAG and the build recipe's tag together; rebuild (just lightgbm-build, which refuses a moved tag with no matching commit recorded); run the equality gate and read its log rather than its exit code — the gate trains at verbosity=1 so LightGBM's unknown-parameter warnings are visible, and they arrive on stdout, which is why run_config returns captured stdout; regenerate the golden fixtures with capture_the_golden_fixture; run the default lane on a box with no binary so the fixture's provenance test fails if fixture and pin disagree. A changed golden number is a finding, not a chore. The lightgbm CI job runs the binary-driven suites through a script that refuses a suite executing zero tests, because a skipped test passes and 0 passed is the shape of a green job that proved nothing.

Telling a benign bump from a format change, cheapest first: the version= line (moved off MODEL_VERSION means a parser project, not a bump); the presence and shape of cat_boundaries= / cat_threshold= in a model trained with a categorical column; and a diff of the header key set between old and new fixture — the only cheap signal that something was added, the case the version check cannot see.

The third file: the category map

crates/vike-ml/src/categories.rs is the stable string-to-integer table for a categorical feature, and its header explains why it must exist: the data file TrainData::write_csv hands LightGBM carries numbers, so a category was already an integer before the trainer saw it, and the saved model has no record of what that integer meant — a CLI-trained model's pandas_categorical: trailer is null. The caller keeps the mapping, in this shape: ids assigned from 0 in declaration order, one label per line, saved beside the model artifact.

Two properties the walker depends on. Ids are never negative, because a negative category is LightGBM's "missing" and routes right unconditionally. And an unknown label encodes as NaN (CategoryMap::encode), not a fallback id — NaN is exactly what a categorical node treats as missing, the honest answer for a category the model never saw; mapping it onto an existing id would predict as if it were a different category, and nothing would say so.

from_labels refuses what would corrupt the mapping on reload: a duplicate label, a label containing a newline, one starting with # (read back as a comment), and an empty or whitespace-padded one (from_text trims and drops blank lines, so it would vanish and shift every later id). The order is the mapping — a reordered file is a different map. to_text and from_text are pure; where the file lives is the caller's decision.