How We Version Adapters That Share a Base Model

Define adapter identity, semantic versions, and base-model compatibility. The useful result is a method that preserves evidence, exposes constraints, and makes the next decision reviewable. This note describes an engineering workflow rather than a claim about a particular organization or production event.

Establish the boundary

Separate adapter slug, adapter version, base-model revision, and file digest. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

Use a fixed holdout or review sample for this step. It should include normal records, rare boundary cases, and at least one input designed to fail safely. A useful change improves the intended condition without removing evidence about a known limitation.

Major, minor, and patch changes for weights and metadata

Define major, minor, and patch changes for weights and metadata. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

Why replacing a file under an existing version is prohibited

Explain why replacing a file under an existing version is prohibited. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

Compatibility and evaluation evidence in a release manifest

Record compatibility and evaluation evidence in a release manifest. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

Handle two adapters targeting the same base without naming collisions

Handle two adapters targeting the same base without naming collisions. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

A rollback that keeps old artifacts addressable

Show a rollback that keeps old artifacts addressable. Keep the relevant source version, configuration, and stable identifier together while this work is performed. That gives a reviewer a direct path from an observed outcome to the input and rule that produced it. Treat automatic checks and human judgment as separate controls, then record both in the release or incident note.

Practical check

Example JSON manifest and version decision table. The example below is intentionally small enough to run as a preflight check before a longer release, migration, or build workflow.

curl -fsSLO https://your-instance.example/download/qwen7b-ticket-triage
shasum -a 256 qwen7b-ticket-triage

Evidence for the next decision

Keep the input digest, outcome, and reviewer note with the resulting artifact or postmortem. Claiming semantic versioning can encode model quality by itself. When the current evidence is incomplete, preserve the failing example, define the missing validation, and defer promotion until the result can be compared fairly.

Make the process idempotent. Repeating the same step on unchanged input should not append metadata, discard extra detail, or silently change ownership. Idempotence makes retries safe and exposes hidden state when outputs differ.

Review results by failure category rather than a single blended number. A small number of high-risk failures can outweigh an improvement on common cases, particularly when the output feeds a release or escalation workflow.

Keep accepted and rejected examples together. A concise rejected sample with its expected outcome is a durable regression test and prevents the same edge condition from returning as an unexplained surprise.

Use a separate holdout set for release decisions. Training records can guide implementation, but they cannot demonstrate that the process behaves correctly on new wording, new sources, or a changed input order.