From 0526e5ba36f448a3b35d06819215db301071b356 Mon Sep 17 00:00:00 2001
From: jamiepine <32987599+jamiepine@users.noreply.github.com>
Date: Sat, 3 Oct 2026 09:41:49 +0000
Subject: [PATCH] docs(offline-guard): state exactly which cache checks were
 extended

---
 CHANGELOG.md                                 | 11 +++++++----
 backend/backends/chatterbox_backend.py       |  7 ++++---
 backend/backends/chatterbox_turbo_backend.py |  9 +++++----
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20cb5824..bfb7aa36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,10 +19,13 @@
   which the wrapper installed in the same release now catches at the source, so the guard no
   longer trips it. The per-file HEAD retries from
   [#434](https://github.com/jamiepine/voicebox/issues/434) were never covered by that wrapper.
-  Because a load now fails hard offline when any file is missing, every backend's cache check
-  lists the full set of files its load reads (Chatterbox tokenizer/conds, TADA's Llama
-  tokenizer mirror), so a partially downloaded snapshot reports "not cached" and downloads
-  online instead.
+  Because a load now fails hard offline when any file is missing, the Chatterbox, Chatterbox
+  Turbo, and TADA cache checks were extended to the small files their loaders also read
+  (tokenizer files, `conds.pt`, TADA's Llama tokenizer mirror) so a snapshot missing one of
+  them reports "not cached" and downloads online instead. The other engines still gate on
+  their weight files (plus `config.json` for Kokoro); transformers-based loaders fetch config
+  before weights, so a weights-present cache normally holds the rest, but that is an
+  assumption, not a check.
 
 ### Linux
 
diff --git a/backend/backends/chatterbox_backend.py b/backend/backends/chatterbox_backend.py
index 234e74d3..34334758 100644
--- a/backend/backends/chatterbox_backend.py
+++ b/backend/backends/chatterbox_backend.py
@@ -29,9 +29,10 @@ logger = logging.getLogger(__name__)
 
 CHATTERBOX_HF_REPO = "ResembleAI/chatterbox"
 
-# Every file ChatterboxMultilingualTTS.from_pretrained() downloads (chatterbox-tts
-# 0.1.7, mtl_tts.py allow_patterns). The load runs with HF offline mode forced
-# when this reports cached, so a partial snapshot must not count as cached.
+# The files ChatterboxMultilingualTTS.from_pretrained() downloads, as of
+# chatterbox-tts 0.1.7 (mtl_tts.py allow_patterns). The load runs with HF
+# offline mode forced when this reports cached, so a partial snapshot must not
+# count as cached -- if upstream adds a file to that list, add it here too.
 _MTL_WEIGHT_FILES = [
     "t3_mtl23ls_v2.safetensors",
     "s3gen.pt",
diff --git a/backend/backends/chatterbox_turbo_backend.py b/backend/backends/chatterbox_turbo_backend.py
index 41273bca..6db526f9 100644
--- a/backend/backends/chatterbox_turbo_backend.py
+++ b/backend/backends/chatterbox_turbo_backend.py
@@ -29,10 +29,11 @@ logger = logging.getLogger(__name__)
 
 CHATTERBOX_TURBO_HF_REPO = "ResembleAI/chatterbox-turbo"
 
-# Every file ChatterboxTurboTTS.from_local() reads (chatterbox-tts 0.1.7): the
-# three weight files, the GPT-2 tokenizer files AutoTokenizer needs, and the
-# built-in voice. The load runs with HF offline mode forced when this reports
-# cached, so a partial snapshot must not count as cached.
+# The files ChatterboxTurboTTS.from_local() reads, as of chatterbox-tts 0.1.7:
+# the three weight files, the GPT-2 tokenizer files AutoTokenizer needs, and
+# the built-in voice. The load runs with HF offline mode forced when this
+# reports cached, so a partial snapshot must not count as cached -- if upstream
+# starts reading another file, add it here too.
 _TURBO_WEIGHT_FILES = [
     "t3_turbo_v1.safetensors",
     "s3gen_meanflow.safetensors",