@@ -1013,6 +1037,10 @@ export async function showModelModal(model, modelType) {
const activeModalElement = document.getElementById(modalId);
if (activeModalElement) {
activeModalElement.dataset.filePath = modelWithFullData.file_path || '';
+ // Metadata provenance: the description tab reads this to explain why the
+ // text is unavailable instead of showing a generic "failed to load".
+ activeModalElement.dataset.metadataPartial = metadataPartial ? 'true' : 'false';
+ activeModalElement.dataset.metadataOffline = metadataOffline ? 'true' : 'false';
// Store usage_tips for LoRA models
if (modelType === 'loras' && modelWithFullData.usage_tips) {
activeModalElement.dataset.usageTips = modelWithFullData.usage_tips;
diff --git a/tests/conftest.py b/tests/conftest.py
index 78fcf34c..8d9439ad 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -285,6 +285,9 @@ class MockModelService:
async def get_model_metadata(self, *_args, **_kwargs): # pragma: no cover
return {}
+ async def get_model_metadata_with_fallback(self, *_args, **_kwargs): # pragma: no cover
+ return {}, False, False
+
async def get_model_description(self, *_args, **_kwargs): # pragma: no cover
return ""
diff --git a/tests/frontend/components/modelMetadata.renamePath.test.js b/tests/frontend/components/modelMetadata.renamePath.test.js
index 9b82f5aa..149992d6 100644
--- a/tests/frontend/components/modelMetadata.renamePath.test.js
+++ b/tests/frontend/components/modelMetadata.renamePath.test.js
@@ -177,10 +177,10 @@ describe('Model metadata interactions keep file path in sync', () => {
it('uses the latest file path when saving notes', async () => {
const saveModelMetadata = vi.fn().mockResolvedValue({ success: true });
- const fetchModelMetadata = vi.fn().mockResolvedValue(null);
+ const fetchModelMetadataWithStatus = vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false });
getModelApiClient.mockReturnValue({
- fetchModelMetadata,
+ fetchModelMetadataWithStatus,
saveModelMetadata,
});
@@ -209,10 +209,10 @@ describe('Model metadata interactions keep file path in sync', () => {
});
it('shows recipes tab for checkpoint modals and loads linked recipes by hash', async () => {
- const fetchModelMetadata = vi.fn().mockResolvedValue(null);
+ const fetchModelMetadataWithStatus = vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false });
getModelApiClient.mockReturnValue({
- fetchModelMetadata,
+ fetchModelMetadataWithStatus,
saveModelMetadata: vi.fn(),
});
diff --git a/tests/frontend/components/modelModal.hashes.test.js b/tests/frontend/components/modelModal.hashes.test.js
index 173a65d3..5aedb928 100644
--- a/tests/frontend/components/modelModal.hashes.test.js
+++ b/tests/frontend/components/modelModal.hashes.test.js
@@ -126,7 +126,7 @@ describe('Model modal hash rendering', () => {
copyToClipboard.mockReset();
calculateModelHash = vi.fn();
getModelApiClient.mockReturnValue({
- fetchModelMetadata: vi.fn().mockResolvedValue(null),
+ fetchModelMetadataWithStatus: vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false }),
saveModelMetadata: vi.fn(),
calculateModelHash,
});
diff --git a/tests/frontend/components/modelModal.licenseIcons.test.js b/tests/frontend/components/modelModal.licenseIcons.test.js
index ba7a291b..c0d95f2a 100644
--- a/tests/frontend/components/modelModal.licenseIcons.test.js
+++ b/tests/frontend/components/modelModal.licenseIcons.test.js
@@ -112,9 +112,9 @@ describe('Model modal license rendering', () => {
});
it('handles aggregated commercial strings without extra restrictions (classic style)', async () => {
- const fetchModelMetadata = vi.fn().mockResolvedValue(null);
+ const fetchModelMetadataWithStatus = vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false });
getModelApiClient.mockReturnValue({
- fetchModelMetadata,
+ fetchModelMetadataWithStatus,
saveModelMetadata: vi.fn(),
});
diff --git a/tests/frontend/components/modelModal.metadataFallback.test.js b/tests/frontend/components/modelModal.metadataFallback.test.js
new file mode 100644
index 00000000..b2d9be79
--- /dev/null
+++ b/tests/frontend/components/modelModal.metadataFallback.test.js
@@ -0,0 +1,208 @@
+import { describe, it, beforeEach, expect, vi } from 'vitest';
+
+const {
+ MODAL_MODULE,
+ API_FACTORY,
+ UI_HELPERS_MODULE,
+ MODAL_MANAGER_MODULE,
+ SHOWCASE_MODULE,
+ MODEL_TAGS_MODULE,
+ UTILS_MODULE,
+ TRIGGER_WORDS_MODULE,
+ PRESET_TAGS_MODULE,
+ MODEL_VERSIONS_MODULE,
+ RECIPE_TAB_MODULE,
+ I18N_HELPERS_MODULE,
+} = vi.hoisted(() => ({
+ MODAL_MODULE: new URL('../../../static/js/components/shared/ModelModal.js', import.meta.url).pathname,
+ API_FACTORY: new URL('../../../static/js/api/modelApiFactory.js', import.meta.url).pathname,
+ UI_HELPERS_MODULE: new URL('../../../static/js/utils/uiHelpers.js', import.meta.url).pathname,
+ MODAL_MANAGER_MODULE: new URL('../../../static/js/managers/ModalManager.js', import.meta.url).pathname,
+ SHOWCASE_MODULE: new URL('../../../static/js/components/shared/showcase/ShowcaseView.js', import.meta.url).pathname,
+ MODEL_TAGS_MODULE: new URL('../../../static/js/components/shared/ModelTags.js', import.meta.url).pathname,
+ UTILS_MODULE: new URL('../../../static/js/components/shared/utils.js', import.meta.url).pathname,
+ TRIGGER_WORDS_MODULE: new URL('../../../static/js/components/shared/TriggerWords.js', import.meta.url).pathname,
+ PRESET_TAGS_MODULE: new URL('../../../static/js/components/shared/PresetTags.js', import.meta.url).pathname,
+ MODEL_VERSIONS_MODULE: new URL('../../../static/js/components/shared/ModelVersionsTab.js', import.meta.url).pathname,
+ RECIPE_TAB_MODULE: new URL('../../../static/js/components/shared/RecipeTab.js', import.meta.url).pathname,
+ I18N_HELPERS_MODULE: new URL('../../../static/js/utils/i18nHelpers.js', import.meta.url).pathname,
+}));
+
+vi.mock(UI_HELPERS_MODULE, () => ({
+ showToast: vi.fn(),
+ openCivitai: vi.fn(),
+ copyToClipboard: vi.fn(),
+}));
+
+vi.mock(MODAL_MANAGER_MODULE, () => ({
+ modalManager: {
+ showModal: vi.fn((id, html) => {
+ document.body.innerHTML = `
${html}
`;
+ }),
+ closeModal: vi.fn(),
+ },
+}));
+
+vi.mock(SHOWCASE_MODULE, () => ({
+ scrollToTop: vi.fn(),
+ loadExampleImages: vi.fn(),
+}));
+
+vi.mock(MODEL_TAGS_MODULE, () => ({
+ setupTagEditMode: vi.fn(),
+}));
+
+vi.mock(UTILS_MODULE, async (importOriginal) => {
+ const actual = await importOriginal();
+ return {
+ ...actual,
+ renderCompactTags: vi.fn(() => ''),
+ setupTagTooltip: vi.fn(),
+ formatFileSize: vi.fn(() => '1 MB'),
+ };
+});
+
+vi.mock(TRIGGER_WORDS_MODULE, () => ({
+ renderTriggerWords: vi.fn(() => ''),
+ setupTriggerWordsEditMode: vi.fn(),
+}));
+
+vi.mock(PRESET_TAGS_MODULE, () => ({
+ parsePresets: vi.fn(() => ({})),
+ renderPresetTags: vi.fn(() => ''),
+}));
+
+vi.mock(MODEL_VERSIONS_MODULE, () => ({
+ initVersionsTab: vi.fn(() => ({
+ load: vi.fn().mockResolvedValue(undefined),
+ })),
+}));
+
+vi.mock(RECIPE_TAB_MODULE, () => ({
+ loadRecipesForModel: vi.fn(),
+}));
+
+vi.mock(I18N_HELPERS_MODULE, () => ({
+ translate: vi.fn((_, __, fallback) => fallback || ''),
+}));
+
+vi.mock('../../../static/js/api/apiConfig.js', () => ({
+ MODEL_TYPES: {
+ LORA: 'loras',
+ CHECKPOINT: 'checkpoints',
+ EMBEDDING: 'embeddings',
+ },
+}));
+
+vi.mock(API_FACTORY, () => ({
+ getModelApiClient: vi.fn(),
+}));
+
+function makeModel(overrides = {}) {
+ return {
+ model_name: 'Offline Model',
+ file_path: 'models/offline.safetensors',
+ file_name: 'offline.safetensors',
+ civitai: {
+ modelId: 7,
+ name: 'v1.0',
+ creator: { username: 'artist' },
+ },
+ ...overrides,
+ };
+}
+
+describe('Model modal metadata fallback', () => {
+ let getModelApiClient;
+ let fetchModelMetadataWithStatus;
+
+ beforeEach(async () => {
+ document.body.innerHTML = '';
+ ({ getModelApiClient } = await import(API_FACTORY));
+ getModelApiClient.mockReset();
+ fetchModelMetadataWithStatus = vi.fn();
+ getModelApiClient.mockReturnValue({
+ fetchModelMetadataWithStatus,
+ saveModelMetadata: vi.fn(),
+ });
+ });
+
+ async function renderModal(model) {
+ const { showModelModal } = await import(MODAL_MODULE);
+ await showModelModal(model, 'loras');
+ return document.getElementById('modelModal');
+ }
+
+ it('merges the cached payload into the list-level civitai data', async () => {
+ fetchModelMetadataWithStatus.mockResolvedValue({
+ metadata: {
+ name: 'v2.0',
+ creator: { username: 'artist' },
+ },
+ partial: true,
+ offline: true,
+ });
+
+ const modal = await renderModal(makeModel());
+
+ expect(modal.querySelector('.version-name-content').textContent).toBe('v2.0');
+ expect(modal.querySelector('.creator-username').textContent).toBe('artist');
+ // The list payload's model id must survive a partial response.
+ expect(modal.querySelector('.civitai-id-entry .model-hash-value').textContent).toBe('7');
+ });
+
+ it('shows the offline notice and flags the modal for the description tab', async () => {
+ fetchModelMetadataWithStatus.mockResolvedValue({
+ metadata: { name: 'v2.0' },
+ partial: true,
+ offline: true,
+ });
+
+ const modal = await renderModal(makeModel());
+
+ const notice = modal.querySelector('.modal-metadata-notice');
+ expect(notice).not.toBeNull();
+ expect(notice.classList.contains('modal-metadata-notice--offline')).toBe(true);
+ expect(notice.textContent).toContain('offline');
+ expect(modal.dataset.metadataOffline).toBe('true');
+ expect(modal.dataset.metadataPartial).toBe('true');
+ });
+
+ it('shows the partial notice when the sidecar is unreadable but the disk is online', async () => {
+ fetchModelMetadataWithStatus.mockResolvedValue({
+ metadata: {},
+ partial: true,
+ offline: false,
+ });
+
+ const modal = await renderModal(makeModel());
+
+ const notice = modal.querySelector('.modal-metadata-notice');
+ expect(notice).not.toBeNull();
+ expect(notice.classList.contains('modal-metadata-notice--offline')).toBe(false);
+ expect(notice.textContent).toContain('could not be read');
+ expect(modal.dataset.metadataOffline).toBe('false');
+ });
+
+ it('renders no notice for complete metadata', async () => {
+ fetchModelMetadataWithStatus.mockResolvedValue({
+ metadata: { name: 'v1.0', description: 'About' },
+ partial: false,
+ offline: false,
+ });
+
+ const modal = await renderModal(makeModel());
+
+ expect(modal.querySelector('.modal-metadata-notice')).toBeNull();
+ expect(modal.dataset.metadataOffline).toBe('false');
+ });
+
+ it('keeps the list data when the metadata request fails outright', async () => {
+ fetchModelMetadataWithStatus.mockRejectedValue(new Error('boom'));
+
+ const modal = await renderModal(makeModel());
+
+ expect(modal.querySelector('.creator-username').textContent).toBe('artist');
+ expect(modal.querySelector('.modal-metadata-notice')).toBeNull();
+ });
+});
diff --git a/tests/frontend/components/modelModal.sidecarLocation.test.js b/tests/frontend/components/modelModal.sidecarLocation.test.js
index 12a6a37e..75046c21 100644
--- a/tests/frontend/components/modelModal.sidecarLocation.test.js
+++ b/tests/frontend/components/modelModal.sidecarLocation.test.js
@@ -126,7 +126,7 @@ describe('Model modal sidecar location entry', () => {
getModelApiClient.mockReset();
showToast.mockReset();
getModelApiClient.mockReturnValue({
- fetchModelMetadata: vi.fn().mockResolvedValue(null),
+ fetchModelMetadataWithStatus: vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false }),
saveModelMetadata: vi.fn(),
});
originalMode = state.global.settings.sidecar_storage_mode;
diff --git a/tests/frontend/components/modelModal.sourceLinks.test.js b/tests/frontend/components/modelModal.sourceLinks.test.js
index 354c9041..0ea1eb95 100644
--- a/tests/frontend/components/modelModal.sourceLinks.test.js
+++ b/tests/frontend/components/modelModal.sourceLinks.test.js
@@ -116,7 +116,7 @@ describe('Model modal source links (#1094)', () => {
const { getModelApiClient } = await import(API_FACTORY);
getModelApiClient.mockReset();
getModelApiClient.mockReturnValue({
- fetchModelMetadata: vi.fn().mockResolvedValue(null),
+ fetchModelMetadataWithStatus: vi.fn().mockResolvedValue({ metadata: {}, partial: false, offline: false }),
saveModelMetadata: vi.fn(),
});
});
diff --git a/tests/routes/test_model_metadata_fallback_route.py b/tests/routes/test_model_metadata_fallback_route.py
new file mode 100644
index 00000000..dee9c0e7
--- /dev/null
+++ b/tests/routes/test_model_metadata_fallback_route.py
@@ -0,0 +1,99 @@
+"""Route contract for the degraded ``/metadata`` response.
+
+The model modal relies on the cached payload the service returns when the
+sidecar is unreadable, together with the ``partial`` / ``offline`` flags that
+tell the UI why the payload is incomplete.
+"""
+
+import json
+import logging
+
+from py.routes.handlers.model_handlers import ModelQueryHandler
+
+
+class DummyRequest:
+ def __init__(self, query=None):
+ self.query = query or {}
+
+
+class StubService:
+ model_type = "lora"
+
+ def __init__(self, result=None, error=None):
+ self._result = result
+ self._error = error
+ self.calls = []
+
+ async def get_model_metadata_with_fallback(self, file_path):
+ self.calls.append(file_path)
+ if self._error is not None:
+ raise self._error
+ return self._result
+
+
+def make_handler(service):
+ return ModelQueryHandler(service=service, logger=logging.getLogger("test"))
+
+
+async def test_returns_partial_payload_with_provenance_flags():
+ service = StubService(
+ result=(
+ {
+ "id": 42,
+ "modelId": 7,
+ "name": "v2.0",
+ "creator": {"username": "artist"},
+ "model": {"type": "LORA", "allowNoCredit": False},
+ },
+ True,
+ True,
+ )
+ )
+ response = await make_handler(service).get_model_metadata(
+ DummyRequest({"file_path": "models/offline.safetensors"})
+ )
+ payload = json.loads(response.text)
+
+ assert response.status == 200
+ assert payload["success"] is True
+ assert payload["partial"] is True
+ assert payload["offline"] is True
+ assert payload["metadata"]["creator"] == {"username": "artist"}
+ assert service.calls == ["models/offline.safetensors"]
+
+
+async def test_full_metadata_reports_no_degradation():
+ service = StubService(result=({"name": "v1.0"}, False, False))
+ response = await make_handler(service).get_model_metadata(
+ DummyRequest({"file_path": "models/online.safetensors"})
+ )
+ payload = json.loads(response.text)
+
+ assert response.status == 200
+ assert payload["partial"] is False
+ assert payload["offline"] is False
+
+
+async def test_missing_everywhere_still_404s():
+ service = StubService(result=(None, False, True))
+ response = await make_handler(service).get_model_metadata(
+ DummyRequest({"file_path": "models/gone.safetensors"})
+ )
+
+ assert response.status == 404
+
+
+async def test_missing_file_path_is_rejected():
+ service = StubService(result=({}, False, False))
+ response = await make_handler(service).get_model_metadata(DummyRequest({}))
+
+ assert response.status == 400
+
+
+async def test_service_failure_maps_to_500():
+ service = StubService(error=RuntimeError("boom"))
+ response = await make_handler(service).get_model_metadata(
+ DummyRequest({"file_path": "models/offline.safetensors"})
+ )
+
+ assert response.status == 500
diff --git a/tests/services/test_model_metadata_fallback.py b/tests/services/test_model_metadata_fallback.py
new file mode 100644
index 00000000..faba5ba6
--- /dev/null
+++ b/tests/services/test_model_metadata_fallback.py
@@ -0,0 +1,243 @@
+"""Cached-metadata fallback for the model modal.
+
+When the model's disk is offline the authoritative ``.metadata.json`` cannot be
+read, but the scanner still holds the cache entry. The modal must keep showing
+what the cache retains (creator, version name, trigger words, license
+permissions) instead of falling back to the stripped list payload.
+"""
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from py.services.lora_service import LoraService
+from py.utils.civitai_utils import build_license_flags
+from py.utils.models import LoraMetadata
+
+
+def make_service(entries, *, path_available=True):
+ scanner = Mock()
+ scanner.get_cached_data = AsyncMock(
+ return_value=SimpleNamespace(raw_data=list(entries))
+ )
+ scanner.is_file_path_available = Mock(return_value=path_available)
+ return LoraService(scanner)
+
+
+def make_entry(file_path):
+ return {
+ "file_path": file_path,
+ "file_name": "artist_style",
+ "model_name": "Artist Style",
+ "base_model": "Illustrious",
+ "license_flags": build_license_flags(
+ {
+ "allowNoCredit": False,
+ "allowCommercialUse": ["Image", "Rent"],
+ "allowDerivatives": False,
+ "allowDifferentLicense": True,
+ }
+ ),
+ "civitai": {
+ "id": 42,
+ "modelId": 7,
+ "name": "v2.0",
+ "creator": {"username": "artist"},
+ "trainedWords": ["artist style"],
+ "model": {"type": "LORA"},
+ },
+ }
+
+
+@pytest.fixture
+def offline_model(tmp_path):
+ """A cache entry whose model file and sidecar are on an unreachable root."""
+ file_path = str(tmp_path / "removable" / "artist_style.safetensors")
+ return file_path, make_entry(file_path)
+
+
+async def test_metadata_falls_back_to_cache_entry(offline_model):
+ file_path, entry = offline_model
+ service = make_service([entry], path_available=False)
+
+ metadata, partial, offline = await service.get_model_metadata_with_fallback(file_path)
+
+ assert partial is True
+ assert offline is True
+ assert metadata["creator"] == {"username": "artist"}
+ assert metadata["name"] == "v2.0"
+ assert metadata["id"] == 42
+ assert metadata["modelId"] == 7
+ assert metadata["trainedWords"] == ["artist style"]
+ assert metadata["baseModel"] == "Illustrious"
+
+
+async def test_fallback_decodes_license_permissions(offline_model):
+ file_path, entry = offline_model
+ service = make_service([entry], path_available=False)
+
+ metadata, _partial, _offline = await service.get_model_metadata_with_fallback(file_path)
+
+ assert metadata["model"] == {
+ "type": "LORA",
+ "allowNoCredit": False,
+ "allowCommercialUse": ["Image", "Rent"],
+ "allowDerivatives": False,
+ "allowDifferentLicense": True,
+ }
+
+
+async def test_fallback_does_not_invent_license_data_without_civitai_model(tmp_path):
+ file_path = str(tmp_path / "huggingface" / "flux.safetensors")
+ entry = {
+ "file_path": file_path,
+ "file_name": "flux",
+ "model_name": "Flux",
+ "base_model": "Flux",
+ "license_flags": 127,
+ "civitai": {
+ "trainedWords": ["trigger"],
+ "creator": {"username": "someone"},
+ },
+ }
+ service = make_service([entry], path_available=False)
+
+ metadata, partial, _offline = await service.get_model_metadata_with_fallback(file_path)
+
+ assert partial is True
+ assert "model" not in metadata
+ assert metadata["creator"] == {"username": "someone"}
+
+
+async def test_fallback_matches_forward_slashed_cache_path(offline_model):
+ file_path, entry = offline_model
+ service = make_service([entry], path_available=False)
+
+ # The API echoes the path as the card sent it (host separators on Windows).
+ windows_style = file_path.replace("/", "\\")
+
+ metadata, partial, _offline = await service.get_model_metadata_with_fallback(
+ windows_style
+ )
+
+ assert partial is True
+ assert metadata["name"] == "v2.0"
+
+
+async def test_unknown_path_still_reports_missing_metadata(tmp_path):
+ service = make_service([], path_available=True)
+
+ metadata, partial, offline = await service.get_model_metadata_with_fallback(
+ str(tmp_path / "elsewhere" / "nope.safetensors")
+ )
+
+ assert metadata is None
+ assert partial is False
+ assert offline is False
+
+
+async def test_entry_without_civitai_data_reports_missing_metadata(tmp_path):
+ file_path = str(tmp_path / "plain" / "hf-model.safetensors")
+ entry = {
+ "file_path": file_path,
+ "file_name": "hf-model",
+ "model_name": "HF Model",
+ "base_model": "Flux",
+ "civitai": None,
+ }
+ service = make_service([entry], path_available=False)
+
+ metadata, partial, offline = await service.get_model_metadata_with_fallback(file_path)
+
+ assert metadata is None
+ assert partial is False
+ assert offline is True
+
+
+async def test_sidecar_payload_wins_when_readable(tmp_path, offline_model):
+ file_path, entry = offline_model
+ sidecar = tmp_path / "removable" / "artist_style.metadata.json"
+ sidecar.parent.mkdir(parents=True, exist_ok=True)
+ sidecar.write_text(
+ json.dumps(
+ {
+ "file_name": "artist_style",
+ "model_name": "Artist Style",
+ "file_path": file_path,
+ "size": 1234,
+ "modified": 111.0,
+ "sha256": "a" * 64,
+ "base_model": "Illustrious",
+ "preview_url": "",
+ "civitai": {"name": "v3.0", "creator": {"username": "artist"}},
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ scanner_service = make_service([entry], path_available=True)
+ scanner_service.scanner.sync_cache_from_metadata = AsyncMock(return_value=False)
+
+ metadata, partial, offline = await scanner_service.get_model_metadata_with_fallback(
+ file_path
+ )
+
+ assert partial is False
+ assert offline is False
+ assert metadata["name"] == "v3.0"
+
+
+async def test_offline_path_skips_the_disk_read_in_alongside_mode(
+ offline_model, monkeypatch
+):
+ """A dead share must not be stat()ed just to open the modal."""
+ file_path, entry = offline_model
+ load_metadata = AsyncMock(return_value=(None, False))
+ monkeypatch.setattr(
+ "py.services.base_model_service.MetadataManager.load_metadata", load_metadata
+ )
+ monkeypatch.setattr(
+ "py.services.base_model_service.is_centralized", lambda: False
+ )
+
+ service = make_service([entry], path_available=False)
+ metadata, partial, _offline = await service.get_model_metadata_with_fallback(file_path)
+
+ load_metadata.assert_not_awaited()
+ assert partial is True
+ assert metadata["creator"] == {"username": "artist"}
+
+
+async def test_centralized_storage_still_reads_the_sidecar_when_drive_is_offline(
+ offline_model, monkeypatch
+):
+ """Centralized sidecars sit on the app disk, so the real payload survives."""
+ file_path, entry = offline_model
+ sidecar_payload = LoraMetadata(
+ file_name="artist_style",
+ model_name="Artist Style",
+ file_path=file_path,
+ size=1234,
+ modified=111.0,
+ sha256="a" * 64,
+ base_model="Illustrious",
+ preview_url="",
+ civitai={"name": "v3.0", "creator": {"username": "artist"}},
+ )
+ monkeypatch.setattr(
+ "py.services.base_model_service.MetadataManager.load_metadata",
+ AsyncMock(return_value=(sidecar_payload, False)),
+ )
+ monkeypatch.setattr(
+ "py.services.base_model_service.is_centralized", lambda: True
+ )
+ service = make_service([entry], path_available=False)
+ service.scanner.sync_cache_from_metadata = AsyncMock(return_value=False)
+
+ metadata, partial, offline = await service.get_model_metadata_with_fallback(file_path)
+
+ assert partial is False
+ assert offline is True
+ assert metadata["name"] == "v3.0"
diff --git a/tests/utils/test_civitai_license_decode.py b/tests/utils/test_civitai_license_decode.py
new file mode 100644
index 00000000..50ec0e98
--- /dev/null
+++ b/tests/utils/test_civitai_license_decode.py
@@ -0,0 +1,86 @@
+"""Decoding tests for the cached license bitfield.
+
+The persistent cache keeps license permissions as a single integer. When the
+on-disk metadata is unreachable (offline drive) the modal renders its license
+icons from that integer, so the decode must reproduce the exact CivitAI payload
+shape ``build_license_flags`` encoded.
+"""
+
+import pytest
+
+from py.utils.civitai_utils import (
+ build_license_flags,
+ decode_license_flags,
+ resolve_license_payload,
+)
+
+PERMUTATIONS = [
+ {
+ "allowNoCredit": True,
+ "allowCommercialUse": ["Sell"],
+ "allowDerivatives": True,
+ "allowDifferentLicense": True,
+ },
+ {
+ "allowNoCredit": False,
+ "allowCommercialUse": ["Image", "RentCivit", "Rent", "Sell"],
+ "allowDerivatives": True,
+ "allowDifferentLicense": True,
+ },
+ {
+ "allowNoCredit": False,
+ "allowCommercialUse": [],
+ "allowDerivatives": False,
+ "allowDifferentLicense": False,
+ },
+ {
+ "allowNoCredit": True,
+ "allowCommercialUse": ["Image", "Rent"],
+ "allowDerivatives": False,
+ "allowDifferentLicense": True,
+ },
+]
+
+
+@pytest.mark.parametrize("payload", PERMUTATIONS)
+def test_decode_round_trips_build_license_flags(payload):
+ assert decode_license_flags(build_license_flags(payload)) == payload
+
+
+def test_decode_maps_each_commercial_bit_to_its_civitai_value():
+ base = {
+ "allowNoCredit": False,
+ "allowDerivatives": False,
+ "allowDifferentLicense": False,
+ }
+
+ for value in ("Image", "RentCivit", "Rent", "Sell"):
+ decoded = decode_license_flags(build_license_flags({**base, "allowCommercialUse": [value]}))
+ assert decoded["allowCommercialUse"] == [value]
+
+
+def test_decode_keeps_full_permission_combination():
+ flags = build_license_flags(
+ {
+ "allowNoCredit": True,
+ "allowCommercialUse": ["Image", "RentCivit", "Rent", "Sell"],
+ "allowDerivatives": True,
+ "allowDifferentLicense": True,
+ }
+ )
+
+ assert flags == 127
+ assert decode_license_flags(flags) == {
+ "allowNoCredit": True,
+ "allowCommercialUse": ["Image", "RentCivit", "Rent", "Sell"],
+ "allowDerivatives": True,
+ "allowDifferentLicense": True,
+ }
+
+
+def test_decode_falls_back_to_civitai_defaults_for_invalid_input():
+ expected = decode_license_flags(build_license_flags({}))
+
+ assert decode_license_flags(None) == expected
+ assert decode_license_flags("not-a-number") == expected
+ assert expected == resolve_license_payload({})