Version On-Device Model Artifacts Reproducibly

Direct answer

Version an on-device model by the exact inputs needed to reproduce and activate it, not by a family label or a filename. A useful release record binds upstream repository and immutable commit, source file set, license reference, tokenizer and template revisions, conversion tool and options, output package identity, expected length and digest if verified, runtime revision, application build, and acceptance fixture version. Store these relationships in a manifest or release record that remains available after updates. The version string should be stable and human-readable, but it must point to immutable underlying content; a label such as “latest” is a channel pointer, not an artifact identity. The local project already demonstrates why versioning matters: ModelConfig binds the E2B URL to a commit, while the E4B URL and expected size are explicitly documented as placeholders. The current E2B SHA-256 is empty. COVE-MODEL-01, COVE-MODEL-02, and COVE-MODEL-03 distinguish a pinned artifact from unverified or placeholder metadata. These are local source facts, not a public release catalogue. No page should translate a repository file into a claim that an artifact is publicly downloadable, device-supported, or production-released. Keep source revision and derived artifact revision distinct. A conversion can produce new bytes without changing the upstream commit; changing quantization flags can produce another output from the same source; changing tokenizer or chat template can alter behavior while weights remain identical. Therefore one version field cannot represent every dependency. Use a manifest with named components and hashes or immutable references where available. If some digest is missing, identify that field as unavailable and retain source revision, byte count provenance, and build metadata as separate facts rather than fabricating a complete-looking version. Reproducibility requires capturing the build environment enough to explain meaningful changes: converter commit, package versions, runtime release, target format, options, calibration data identity and rights, and scripts. Do not save private prompts or user content in a model manifest. Avoid floating dependency versions in release records; record the resolved version even if a build file uses a dynamic selector. If dependencies or upstream assets change, create a new candidate and rerun acceptance. A model family’s published capabilities or parameter count do not identify the exact file used by the app. Versioning also governs caches and user-derived state. Embeddings, token caches, compiled artifacts, conversation summaries, or generated indexes can depend on the model, tokenizer, preprocessing, or runtime. Store the relevant dependency keys with derived records, then invalidate only the records whose dependencies changed. Preserve source conversations and user files unless a separate, explicit policy says otherwise. On rollback, restore a compatible set of model and runtime identities; do not silently reinterpret prior derived values with a different artifact. Design a release manifest that is machine-checkable but reviewable. It should distinguish upstream source, converted package, runtime, application, optional assets, expected integrity metadata, test fixtures, and approval status. Include a clear relationship edge—“built from,” “requires,” or “validated with”—so auditors can tell whether a digest covers source weights or the final packaged file. Publish a digest only when the value was generated from the exact bytes through a trusted workflow and independently checked. A checksum copied from a different quantization or mirror does not establish artifact identity. ### Procedure 1. Define a component graph for each model release: source repo/revision, source files, tokenizer/template, conversion recipe, final package, runtime, app build, and dependent derived data. 2. Assign immutable identifiers to each changed byte set. Record full upstream commit, toolchain versions, resolved runtime package, manifest revision, and digest provenance; leave unavailable fields explicitly unknown. 3. Store the release manifest with the build and test artifacts. Make clear which digest covers which file, which runtime supports the package, and which fixture set was used for acceptance. 4. Add update and rollback tests. Verify that the app selects the intended manifest, detects a changed dependency, invalidates only dependent caches, and can restore the prior compatible combination. 5. Review public statements against the manifest and distribution evidence. Do not turn a pinned repository revision into an APK, store listing, support, or availability claim. ### Acceptance criteria - Every release identity resolves to immutable source and final-package inputs; mutable branch names are not treated as exact artifact versions. - Source, conversion, tokenizer, runtime, application, and test-fixture revisions are separately represented with explicit relationships. - Missing digests or placeholder fields are marked unknown, and no unsupported release or compatibility claim is derived from them. - Rollback restores a recorded compatible set and invalidates only dependent derived data while preserving user-authored records. ### Comparison | Identifier | Meaning | Limitation | |---|---|---| | Model family name | Human-readable family or variant label | Does not select exact revision, conversion, or runtime | | Repository commit | Immutable upstream repository state | Does not identify converted output bytes or app integration | | Release manifest | Links source, output, runtime, app, and tests | Trust depends on accurate generation and verification of each field | ### FAQ **Is a model name enough to reproduce a release?** No. The same family can have different commits, tokenizers, conversions, quantization settings, package contents, and runtime requirements. Record exact revisions and their relationships in a manifest. **Can a branch called main be used as a production version?** It is mutable and can point to different content over time. Resolve and record an immutable commit for each release candidate, then bind the packaged output and validation record to it. **Should the app version and model version be identical?** Not necessarily. They are separate components with an explicit compatibility relation. An app can support several model artifacts, and one artifact may have different acceptance results under different runtimes. **What if the model digest is unavailable?** Keep the field unknown and record other provenance separately. Do not claim checksum verification; establish an approved source and create a trusted digest from the exact final bytes before making that claim.

A release must be recreated after a runtime upgrade

A team receives a report that a model task changed after the app’s runtime was upgraded. The release record contains only a family name and a mutable download URL, so developers cannot identify which source, conversion, tokenizer, or package the user actually had.

Decision

Create a manifest that separates each dependency and binds the final package and acceptance record to immutable identities.

Expected outcome

The team can reconstruct the candidate chain, compare the old and new combinations, and roll back without guessing which file the family name represented.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Pinned revision
• Release manifest
• Rollback artifact

A runtime comparison is publishable only when artifact identity, build configuration, selected backend, task fixture, and failures are recorded.

Implementation workflow

1. Map every release dependency. List upstream source, tokenizer, template, conversion recipe, final package, runtime, app build, optional assets, and derived data. Mark which combinations are independent and which are validated together.
2. Resolve mutable references. Replace branch or latest references with a full immutable commit in the release record. Store the resolved package version even when build configuration uses a dynamic selector.
3. Generate and review the manifest. Record output file identity, digest provenance, length source, toolchain, and relationships such as built-from and validated-with. A missing value remains unknown rather than being inferred.
4. Bind tests and compatibility decisions. Associate versioned fixtures, runtime load results, and task acceptance with the exact manifest combination. Keep platform or device conclusions limited to the tested record.
5. Test upgrade and rollback paths. Change one dependency at a time, verify cache invalidation, and confirm rollback restores a compatible set while retaining user-authored data.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• A release manifest uniquely resolves the source and final package without depending on a mutable label.
• Runtime, tokenizer, app and test fixture versions are not conflated with the model-family name.
• Digest status and distribution state are represented only when independently verified.
• A prior release can be reconstructed and restored using its recorded compatible component set.

Decision table

Failure patterns to prevent

• Following main forever
• Using family name as artifact identity

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Cove Gemma 4 model page
• Hugging Face Hub downloads at a specific revision
• Hugging Face repositories, commits, and history
• LiteRT-LM package builder and inspect tools

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions