V 3

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+voice.pyz filter=lfs diff=lfs merge=lfs -text

DOCS.md

@@ -1,22 +1,21 @@
 # voice — Help
 
-Generated from `voice --help` and `voice <cmd> --help` (v2.1.1, 13 commands).
+Generated from `voice --help` and `voice <cmd> --help` (v3.0, 12 commands).
 
 ## voice --help
 
 ```text
 usage: voice [-h] [-v] [--non-interactive] [--version]
              [--completion {bash,zsh,fish}]
-             {get,cast,tensor,delta,add,list,info,remove,cleanup,auth,report,path,doctor} ...
+             {get,cast,delta,add,list,info,remove,cleanup,auth,report,path,doctor} ...
 
 Lift a model's voice and cast it onto another model.
 
 positional arguments:
-  {get,cast,tensor,delta,add,list,info,remove,cleanup,auth,report,path,doctor}
+  {get,cast,delta,add,list,info,remove,cleanup,auth,report,path,doctor}
     get                 Get a voice from a model (safetensors repo, .gguf, or
                         URL)
     cast                Cast a voice onto a .gguf or .safetensors file
-    tensor              Extract or cast any named tensor
     delta               Make a reusable style (voice − base)
     add                 Add a voice from local voice.safetensors + voice.json
     list                List stored voices
@@ -40,15 +39,22 @@ options:
 ## voice get
 
 ```text
-usage: voice get [-h] [-q] [--name NAME] [--yes] source
+usage: voice get [-h] [-q] [--name NAME] [--multi] [--out OUT] [--yes]
+                 source [tensors ...]
 
 positional arguments:
   source       HF model ID, .gguf/.safetensors path, or URL
+  tensors      Tensor name(s) to fetch (default: auto-detect output head; 2+
+               or --multi saves a voicepack)
 
 options:
   -h, --help   show this help message and exit
   -q, --quiet
-  --name NAME  Voice name to save
+  --name NAME  Voice name to save (registry voices only)
+  --multi      Fetch several tensors -> voicepack.safetensors + voicepack.json
+               (needs 1+ tensor)
+  --out OUT    Write a standalone file instead of a registry voice (default
+               pack name: voicepack.safetensors)
   --yes
 ```
 
@@ -61,21 +67,27 @@ slugified from the source (`./my model.gguf` → `my-model`); an explicit
 ## voice cast
 
 ```text
-usage: voice cast [-h] [--out OUT] [--yes] [--quant QUANT] target voice
+usage: voice cast [-h] [--out OUT] [--yes] [--quant QUANT]
+                  [--exclude EXCLUDES] [--speak]
+                  target voice [tensors ...]
 
 positional arguments:
-  target      Path to the target .gguf or .safetensors
-  voice       Voice name, or a .safetensors/.gguf path
+  target              Path to the target .gguf or .safetensors
+  voice               Voice name, or a .safetensors/.gguf path
+  tensors             Only cast these tensors (default: every tensor in the
+                      voice)
 
 options:
-  -h, --help  show this help message and exit
-  --out OUT   Output file (default:
-              ~/Voiced/<voice>-<model>/<voice>-<model>.gguf)
+  -h, --help          show this help message and exit
+  --out OUT           Output file (default:
+                      ~/Voiced/<voice>-<model>/<voice>-<model>.gguf)
   --yes
-  --quant QUANT  Output quant override: keep (default, preserve quality) |
-                 target | any quant (q8_0,q4_0,q4_k,q6_k,iq4_nl,f16,f32,bf16,...)
+  --quant QUANT       Output quant override: keep (default, preserve quality)
+                      | target | any quant
+                      (q8_0,q4_0,q4_k,q6_k,iq4_nl,f16,f32,bf16,...)
+  --exclude EXCLUDES  Skip this tensor on cast (repeatable or comma-separated)
+  --speak             Voice speaks through output.weight (invented if absent)
 ```
-
 Philosophy: preserve quality, avoid dequant→quant cycles. Safetensors high-fidelity
 lm_head is quantized once to Q8_0 (Q4 saves little: Q8_0 1.062 vs Q4_0 0.562 B/param).
 All GGML quants supported (trivial passthrough): Q8_0/Q4_0/Q4_1/Q5_0/Q5_1/Q8_1/Q8_K/
@@ -89,74 +101,6 @@ Generic tensors keep target quant (F32 norms stay F32, never forced Q8_0).
 architecture is unknown the output is labeled `llama` (GGUF requires an arch)
 with a warning. BF16 math uses round-to-nearest-even, not truncation.
 
-## voice tensor
-
-```text
-usage: voice tensor [-h] {get,cast} ...
-
-positional arguments:
-  {get,cast}
-    get       Extract any named tensor to a .safetensors file
-    cast      Cast any named tensor onto a .gguf or .safetensors file
-
-options:
-  -h, --help  show this help message and exit
-```
-
-### voice tensor get
-
-```text
-usage: voice tensor get [-h] [--tensor TENSORS] [--multi] [--out OUT] [--yes]
-                        source
-
-positional arguments:
-  source            HF model ID, .gguf/.safetensors path, or URL
-
-options:
-  -h, --help        show this help message and exit
-  --tensor TENSORS  Tensor name (repeatable, or comma-separated; default:
-                    auto-detect output head)
-  --multi           Allow multiple tensors -> voicepack.safetensors
-  --out OUT         Output .safetensors path (default voicepack.safetensors
-                    when --multi)
-  --yes
-```
-
-Shows `Voice 'name' is <quant> <shape> → target` by default. BF16 is preserved
-(not downconverted to F16). GGUF quants passthrough bit-exact to `voice.gguf`;
-multi-pack dequants quants once to F32 for `voicepack.safetensors` (unavoidable).
-
-### voice tensor cast
-
-```text
-usage: voice tensor cast [-h] [--tensor TENSOR] [--out OUT] [--yes]
-                         [--quant QUANT] [--exclude EXCLUDES]
-                         target tensor_file
-
-positional arguments:
-  target              Path to the target .gguf or .safetensors
-  tensor_file         Path to a .safetensors/.gguf containing the tensor(s)
-
-options:
-  -h, --help          show this help message and exit
-  --tensor TENSOR     Tensor name (default: the file's output head or only
-                      tensor)
-  --out OUT           Output file
-  --yes
-  --quant QUANT       Output quant override: keep (default) | target | any quant
-                      (q8_0,q4_0,q4_k,q6_k,iq4_nl,f16,f32,bf16,...)
-  --exclude EXCLUDES  Skip this tensor on cast (repeatable or comma-separated,
-                      voicepack only)
-```
-
-Keeps target quant by default (F32 norms stay F32, Q4_0 stays Q4_0, never forced
-Q8_0). All quants kept bit-exact (Q1_0/Q8_1/Q8_K/TQ*/MXFP4/NVFP4/IQ* included).
-Mismatch (safetensors F32 → Q8_0 target) prompts `Enter=target` on TTY,
-silent keep-target on `--yes`/pipe. `--exclude` skips listed tensors (fails if
-all excluded). Voicepack cast requires exact tensor match in target (fails instead
-of silently mapping to another tensor; single-tensor cast keeps auto-detect fallback).
-Progress shows `Kept X MB → <quant> @ Y MB/s` plus GGUF write bar.
-
 ## voice delta
 
 ```text

README.md

@@ -6,7 +6,7 @@ language:
 license: apache-2.0
 base_model:
   - google/gemma-4-26B-A4B-it
-base_model_relation: quantized
+base_model_relation: finetune
 tags:
   - gemma
   - moe
@@ -37,13 +37,18 @@ A full model is 26GB. A voice is 1.4GB — smaller models even less. You downloa
 
 ## Two steps to start
 
-One-time setup, then two commands. One model, one voice:
+```bash
+curl -sSL https://huggingface.co/Wiself/voice/resolve/main/voice-cli.tar.gz | tar -xz
+cd voice-cli && python3 voice.py path  # once - adds voice to PATH
+```
+
+Then two commands. One model, one voice:
 
 ```bash
-python3 voice.py path  # once - adds voice to PATH (then use voice directly)
 voice get Gryphe/Gemma-4-26B-A4B-StyleTune-V2
 # Name it styletune-v2 when prompted
 voice cast ./model.gguf styletune-v2 --out ./voiced/
+voice cast ./model.gguf styletune-v2 --speak --out ./voiced/  # voice speaks through output.weight (invented if absent)
 ```
 
 Run it:
@@ -95,13 +100,27 @@ Voice is a **scalpel, not a pipeline** — one idea made trivial: lift a model's
 <summary>What it trivializes (power users, same family & shape)</summary>
 
 * **Same family, any container:** `voice get` from any `safetensors` repo / `.gguf` / URL via range requests; `voice cast` onto any compatible `.gguf` or `.safetensors` — same `vocab` + same `head shape` required, transposes `BF16/F16/F32→Q8_0` auto (`last dim %32==0` else `F16` fallback).
-* **Any single tensor, precisely:** `voice tensor get --tensor <n>` / `tensor cast` for any named tensor — bit-exact when quant types match, validated offsets, otherwise `F32` round-trip.
+* **Any single tensor, precisely:** `voice get <repo> <tensor>` / `voice cast <target> <voice> [tensors...]` for any named tensor — bit-exact when quant types match, validated offsets, otherwise `F32` round-trip.
 * **No surprises:** atomic writes, validated header, ETag-aware resume, `0600` token, symlink-safe — resumes or fails cleanly.
 
 </details>
 
 Keep the stronger model for reasoning, the better voice for style. `llama serve -m` ready.
 
+## One voice, several writers
+
+Where the voice lands changes how the model sounds. We cast one voice (Scarlett) onto one base (Orion) five ways and read every word — same voice, different slots, different writing. The slot is a second dial next to the choice of voice. Full data: [`creative-bench/runs/tensorwars.md`](./creative-bench/runs/tensorwars.md) (one prompt, five builds, single draws — a first probe, more coming).
+
+Every build is Orion with something swapped:
+
+- nothing (the base as it ships),
+- Orion reading through Scarlett's embedding,
+- Orion speaking through Scarlett's head (`--speak`),
+- both slots,
+- one Scarlett tensor serving both slots.
+
+Default cast puts the voice onto `output.weight`, else the embed slot — a target with neither fails loud instead of guessing.
+
 
 ## How it works
 
@@ -151,12 +170,11 @@ The notebook is still mostly empty. That's why the next line matters most.
 
 ## Commands
 
-Three you need daily — rest in [`DOCS.md`](./DOCS.md) (`voice --help` is truth, 13 commands `v2.1.1`):
+Three you need daily — rest in [`DOCS.md`](./DOCS.md) (`voice --help` is truth, 12 commands `v3.0`):
 
 | Command | What it does |
 |---|---|
-| `voice get <model>` | Get a voice — HF `safetensors` repo / `.gguf` / direct URL with Range (same family, head must exist) |
-| `voice cast <target> <voice>` | Cast it onto `.gguf` or `.safetensors` of same shape/vocab (`Q8_0` once for safetensors lm_head, else keep target quant incl. all GGML quants; `--quant keep\|target\|any quant`) |
+| `voice cast <target> <voice> [tensors...]` | Cast it onto `.gguf` or `.safetensors` of same shape/vocab (`Q8_0` once for safetensors lm_head, else keep target quant incl. all GGML quants; `--quant keep\|target\|any quant`; `--speak` for output.weight, invented if absent; `--exclude` to skip) |
 | `voice report -m "note"` | Save a one-line note locally, optionally share to community — small file, big iteration (we pull source/tensor/shape) |
 
 ### Extra commands
@@ -164,8 +182,7 @@ Three you need daily — rest in [`DOCS.md`](./DOCS.md) (`voice --help` is truth
 | Command | What it does |
 |---|---|
 | `voice add <safetensors> <json>` | Add local `voice.safetensors` + `voice.json` to `~/.voices/` (both required, asks name) |
-| `voice tensor get --tensor <n>` | Extract any named tensor (shows quant/shape; `--multi --tensor a,b → voicepack.safetensors`, BF16 preserved) |
-| `voice tensor cast <target> <file>` | Cast any named tensor, keeps target quant (F32 norms stay F32; `--quant`, `--exclude` for packs) |
+| `voice get <repo> [tensors...]` | Extract head (default) or named tensors (`--multi` → `voicepack.safetensors` + json, BF16 preserved) |
 | `voice delta [name]` | Make a portable `voice − base` style |
 | `voice list [base]` | List voices or cached bases |
 | `voice info <voice>` | Show voice details |
@@ -193,7 +210,7 @@ voice list base
 voice cast ./model.gguf styletune-v2 --out ./voiced/
 ```
 
-> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 13 commands). Names are lowercased when saved.
+> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 12 commands). Names are lowercased when saved.
 
 ## What StyleTune showed
 
@@ -316,7 +333,7 @@ print(pipe("Write a short tavern scene with varied diction:")[0]["generated_text
 # pipe = pipeline("text-generation", model="gryphe/gemma-4-26b-a4b-styletune-v2")
 ```
 
-> **Base-model note:** `google/gemma-4-26b-a4b-it` is the lowercased form of the real HF ID [`google/gemma-4-26B-A4B-it`](https://huggingface.co/google/gemma-4-26B-A4B-it) (verified live, Apache-2.0 via Gemma license). `gryphe/gemma-4-26b-a4b-styletune-v2` is the lowercased illustrative voice source—replace with any compatible `safetensors` model that shares architecture and vocab. Relation: `base_model_relation: quantized` (fused GGUF head quantized to `Q8_0`, remainder preserved).
+> **Base-model note:** `google/gemma-4-26b-a4b-it` is the lowercased form of the real HF ID [`google/gemma-4-26B-A4B-it`](https://huggingface.co/google/gemma-4-26B-A4B-it) (verified live, Apache-2.0 via Gemma license). `gryphe/gemma-4-26b-a4b-styletune-v2` is the lowercased illustrative voice source—replace with any compatible `safetensors` model that shares architecture and vocab. Relation: `base_model_relation: finetune` (the voice is lifted from a finetune of this base).
 
 ---
 
@@ -441,7 +458,7 @@ Every wait shows a bar — `→ lm_head.weight 42% · 604/1437 MB · 87 MB/s ·
 <summary>What is inside the files</summary>
 
 - Voice: single-tensor `safetensors`, `lm_head.weight` or `output.weight`, original dtype (`BF16`/`F16`/`F32`), full shape.
-- Delta: single-tensor `safetensors` + tiny marker `delta.voice.marker` (`U8 [1]`) + `__metadata__ {"type":"delta"}`, `F16`, same shape, `voice − base`. Marker lets `voice cast model.gguf delta.safetensors` auto-detect and fuse (just works, no flag, 1 byte overhead, ignored except creation/cast); old `delta-` folders without marker still work via `voice.json type:delta`. Custom `style.delta` (like `Lora/StyleTune/style.safetensors`) is not our marker — intentionally not auto-fused (use `delta-` folder or `voice tensor` explicit if you want it).
+- Delta: single-tensor `safetensors` + tiny marker `delta.voice.marker` (`U8 [1]`) + `__metadata__ {"type":"delta"}`, `F16`, same shape, `voice − base`. Marker lets `voice cast model.gguf delta.safetensors` auto-detect and fuse (just works, no flag, 1 byte overhead, ignored except creation/cast); old `delta-` folders without marker still work via `voice.json type:delta`. Custom `style.delta` (like `Lora/StyleTune/style.safetensors`) is not our marker — intentionally not auto-fused (use `delta-` folder or `voice cast <target> <voice> <tensor>` explicit if you want it).
 - Voiced GGUF: copy of your model with the output head replaced and quantized to `Q8_0`. All other tensors and metadata are preserved. Vocab, tokenizer, and architecture stay exactly as they were.
 
 How it works under the hood:

creative-bench/runs/tensorwars.md

@@ -0,0 +1,130 @@
+# Tensorwars
+
+## Why this exists
+
+A voice is a single tensor extracted from a donor model. A target model has two
+places that tensor can land: the output head (`output.weight`) and the input
+embedding (`token_embd.weight`). Some architectures tie the two (one tensor
+serves both); most do not.
+
+The open question: when casting a voice onto a target, which slot should
+receive it? Output only, input only, both, and the old tied method each place
+the same voice differently. Nothing about the choice is obvious from the weights.
+Donor voice: Scarlett (`dark-scarlett-v1-0-26b-a4b-TheDrummer_Orion-26B-A4B-v1-IQ4_NL.gguf`).
+Base: Orion (`TheDrummer_Orion-26B-A4B-v1-IQ4_NL.gguf`).
+
+| build | voice placement | file served |
+|---|---|---|
+| truebase | none (control) | `TheDrummer_Orion-26B-A4B-v1-IQ4_NL.gguf` |
+| inputOnly | voice → `token_embd` only | `input-experimental.gguf` |
+| outputOnly | voice → `output.weight` only | `exprimental.gguf` (filename as-is) |
+| fullShared | voice → both slots (verbatim input path) | `full-experimental.gguf` |
+| oldTied | one tensor serving both slots (tied) | `dark-scarlett-v1-0-26b-a4b-TheDrummer_Orion-26B-A4B-v1-IQ4_NL.gguf` |
+
+In plain terms, every build is Orion with something swapped:
+
+- truebase: Orion, nothing swapped.
+- inputOnly: Orion reading through Scarlett's embedding, speaking through its own head.
+- outputOnly: Orion reading through its own embedding, speaking through Scarlett's head.
+- fullShared: Orion reading and speaking through Scarlett, both slots.
+- oldTied: one Scarlett tensor serving both slots.
+
+Small isolated probes first: single-tensor fake GGUF targets confirmed each
+placement lands where intended (byte checks on untouched slots, quant checks on
+touched ones) before any text was generated. Then one prompt (Gladiator,
+first-person, ~1000 words), temp 0.0, seed 1234, single-slot server. Every
+build was generated 3 times; the two text-identical draws were kept as the
+measured pair, the outlier recorded and set aside.
+
+## What the method unlocked
+
+Problems: temp-0 generation does not replay on this stack — identical settings
+produce 2–3 distinct outputs per build (within-build char swings: 150–773).
+Every measurement below is one verified draw, not an average. Placement
+proliferates artifacts: five builds to serve, store, and compare per voice.
+
+Possibilities: one downloaded voice yields multiple distinct writings depending
+on application. The choice of slot is a second dial next to the choice of
+voice.
+
+## The core observation
+
+The same voice, applied to different slots, writes differently — and plans
+differently. All five `thinking` traces are mutually distinct (md5-verified);
+shared plan openings range from 48 to 464 chars. The divergence is present
+before the first word of story is written.
+
+## Scope
+
+Initial steps. One prompt, one voice, one base, single draws. The distances
+are real on this data; how far they generalize needs more prompts, more
+voices, and more readers reporting back.
+
+## Data
+
+### Draw variance (chars, 3 draws per build; kept pair identical)
+
+| build | draws | swing |
+|---|---|---|
+| truebase | 4492 / 5001 / 5001 | 509 |
+| inputOnly | 4646 / 5146 / 5146 | 500 |
+| outputOnly | 5022 / 5795 / 5795 | 773 |
+| fullShared | 5849 / 5250 / 5250 | 599 |
+| oldTied | 4838 / 4688 / 4688 | 150 |
+
+### Kept-draw mechanics
+
+| build | chars | words | sents | med sent len | paras | dialogue turns | TTR |
+|---|---|---|---|---|---|---|---|
+| truebase | 5001 | 935 | 55 | 14 | 17 | 6 | 0.474 |
+| inputOnly | 5146 | 961 | 77 | 11 | 24 | 9 | 0.456 |
+| outputOnly | 5795 | 1085 | 83 | 13 | 30 | 12 | 0.446 |
+| fullShared | 5250 | 960 | 64 | 13 | 19 | 7 | 0.468 |
+| oldTied | 4688 | 862 | 58 | 14 | 16 | 4 | 0.493 |
+
+### Shared stems (common char prefix between kept draws)
+
+All five share the first 48 chars (prompt-forced). Base diverges at 48. The
+four voice builds share 55. outputOnly × fullShared run together 182 chars;
+outputOnly × oldTied 158; fullShared × oldTied 158.
+
+### Trigram overlap between builds (Jaccard)
+
+Highest: outputOnly × fullShared 0.0581. Voice–voice pairs: 0.033–0.058.
+Base–voice pairs: 0.026–0.036. Lowest: base × inputOnly 0.0260.
+
+### Voice-only phrasing
+
+127 four-grams appear in ≥2 voice builds and never in base (sound, color,
+stone, smell families; longest shared spans reach 8 words, e.g. `the clatter
+of cart wheels on basalt paving`). Base-only phrasing (856 four-grams) is
+abstract-connective (`a city that had`, `the fact that in`).
+
+### Donor overlap (same prompt generated by the donor model; trigram Jaccard)
+
+outputOnly 0.0274 > oldTied 0.0179 ≈ truebase 0.0179 > inputOnly 0.0159 >
+fullShared 0.0138. Four phrases verified present in both donor and outputOnly
+texts: `distant roar of the crowd`, `the grain dole`, `the emperor himself`,
+`basalt paving stones`.
+
+### Casting
+
+Base names its protagonist Aurelius with Varro as a fellow gladiator. Every
+voice build names him Caius (Verus in oldTied) and makes Varro the lanista or
+his assistant. All five follow one skeleton: dawn → body toll → games
+announced → training → political meditation → evening.
+
+### Subordination markers per 100 words
+
+oldTied 3.36, inputOnly 3.02, fullShared 3.02, truebase 2.35, outputOnly 2.03.
+
+### Generic-cliché screen (16-item starter list)
+
+fullShared 0 hits, oldTied 0, inputOnly 1 (`whisper`), truebase 1
+(`symphony of`), outputOnly 2 (`whisper` ×2, `echoed`).
+
+### Files
+
+`runs/p1-{truebase,inputOnly,outputOnly,fullShared,oldTied}-t0-orion-id1.jsonl`
+with text-identical `-mate.jsonl` repeats and `.provenance.txt` per build.
+Full measurement log: `runs/p1-fiveway-analysis.md`.

vlib/cache.py

@@ -0,0 +1,344 @@
+"""Base-model tensor cache."""
+
+from pathlib import Path
+import json
+import os
+import struct
+from vlib import ctx
+from vlib.ui import _fail, _now_iso, _step, _warn
+from vlib.net import _cleanup_tmp, _safe_id, http_get_json
+from vlib.tensors import _is_ggml_quant, _write_safetensors_streaming, read_safetensors, write_safetensors
+from vlib.sources import _base_paths, open_source
+from vlib.fetch import _fetch_tensor, _resolve_output_name, _source_arch
+from vlib.registry import _assert_not_symlink
+
+
+def _base_rev(base_id, base_file):
+    """Pinned commit sha for a base cache: sidecar .rev wins, else API HEAD (then pin)."""
+    rev_path = base_file.with_suffix(".rev")
+    try:
+        if rev_path.exists():
+            rev = rev_path.read_text().strip()
+            if rev:
+                return rev
+    except Exception:
+        pass
+    rev = None
+    try:
+        rev = http_get_json(f"https://huggingface.co/api/models/{base_id}", timeout=20).get("sha")
+    except Exception:
+        rev = None
+    if rev:
+        try:
+            base_file.parent.mkdir(parents=True, exist_ok=True)
+            tmp = rev_path.with_suffix(".rev.tmp")
+            tmp.write_text(rev + "\n")
+            tmp.replace(rev_path)
+        except Exception:
+            pass
+        return rev
+    return "main"
+
+
+def _cache_validate(base_file, names):
+    """Names neither in the header nor fully covered by file bytes. Empty = trusted."""
+    try:
+        with open(base_file, "rb") as f:
+            hs = struct.unpack("<Q", f.read(8))[0]
+            hdr = json.loads(f.read(hs))
+        size = os.path.getsize(base_file)
+    except Exception:
+        return list(names)
+    missing = []
+    for n in names:
+        info = hdr.get(n)
+        if not isinstance(info, dict):
+            missing.append(n)
+            continue
+        try:
+            off = info["data_offsets"]
+            if not (isinstance(off, (list, tuple)) and len(off) == 2
+                    and 0 <= int(off[0]) <= int(off[1]) and 8 + hs + int(off[1]) <= size):
+                missing.append(n)
+        except Exception:
+            missing.append(n)
+    return missing
+
+
+def _cache_topup_write(base_file, staged):
+    """Append staged tensors to a base cache + atomically rewrite its header.
+    staged: [(name, blob|None, dtype, shape, raw_path|None)] — blob XOR raw_path.
+    Offsets are data-relative so existing entries never shift. Returns new header.
+    Raises OSError on failure; base_file is only ever swapped in whole (tmp+rename)."""
+    _assert_not_symlink(base_file)
+    import shutil
+    # append + atomic header rewrite (offsets are data-relative: existing entries don't shift)
+    with open(base_file, "rb") as f:
+        old_hs = struct.unpack("<Q", f.read(8))[0]
+        old_hdr = json.loads(f.read(old_hs))
+    old_size = os.path.getsize(base_file)
+    old_data_len = old_size - 8 - old_hs
+    new_hdr = {k: v for k, v in old_hdr.items()}
+    off = old_data_len
+    for m, blob, dtype, shape, _rp in staged:
+        nbytes = len(blob) if blob is not None else Path(_rp).stat().st_size
+        new_hdr[m] = {"dtype": dtype, "shape": list(shape), "data_offsets": [off, off + nbytes]}
+        off += nbytes
+    new_hj = json.dumps(new_hdr).encode("utf-8")
+    tmp_new = base_file.with_suffix(".cache.tmp")
+    with open(tmp_new, "wb") as out:
+        out.write(struct.pack("<Q", len(new_hj)))
+        out.write(new_hj)
+        with open(base_file, "rb") as f:
+            f.seek(8 + old_hs)
+            shutil.copyfileobj(f, out, 1 << 20)
+        for _m, blob, _dt, _sh, _rp in staged:
+            if blob is not None:
+                out.write(blob)
+            else:
+                with open(_rp, "rb") as f:
+                    shutil.copyfileobj(f, out, 1 << 20)
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+    try:
+        try:
+            os.chmod(tmp_new, 0o600)
+        except Exception:
+            pass
+        tmp_new.replace(base_file)
+    except Exception as e:
+        try:
+            tmp_new.unlink(missing_ok=True)
+        except Exception:
+            pass
+        raise OSError(f"Could not update base cache: {e}")
+    return new_hdr
+
+
+def _ensure_base_tensors(base_id, names, args=None):
+    """Base cache with per-tensor trust: top-ups what's missing, self-heals partial caches.
+    All fetches pin one revision so a repo update mid-cache can't mix commits. Returns base_file."""
+    tmp = _base_paths(base_id)
+    if tmp is None:
+        _fail(f"  ✗ Invalid base '{base_id}'")
+    base_file, base_json = tmp
+    want = [n for n in names if n != "delta.voice.marker"]
+    if not want:
+        _fail("  ✗ No tensors requested from base.")
+    import fcntl
+    base_file.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = base_file.with_suffix(".lock")
+    try:
+        lock_fh = open(lock_path, "w")
+    except Exception:
+        lock_fh = None
+    try:
+        if lock_fh is not None:
+            try:
+                fcntl.flock(lock_fh, fcntl.LOCK_EX)
+            except Exception:
+                pass
+        return _ensure_base_tensors_locked(base_id, base_file, base_json, want)
+    finally:
+        if lock_fh is not None:
+            try:
+                fcntl.flock(lock_fh, fcntl.LOCK_UN)
+            except Exception:
+                pass
+            try:
+                lock_fh.close()
+            except Exception:
+                pass
+
+
+def _ensure_base_tensors_locked(base_id, base_file, base_json, want):
+    import shutil
+    rev_path = base_file.with_suffix(".rev")
+    legacy = base_file.exists() and not rev_path.exists()
+    if not base_file.exists():
+        _cache_base(base_id, base_file, base_json)
+    elif legacy:
+        # Pre-rev cache of unknown lineage: re-fetch one held tensor at HEAD and
+        # compare bytes. Match -> same lineage, pin HEAD. Differ -> wipe, start over.
+        # Probe failure (offline?) keeps the cache with a loud warning, never wipes.
+        try:
+            with open(base_file, "rb") as f:
+                hs = struct.unpack("<Q", f.read(8))[0]
+                hdr = json.loads(f.read(hs))
+            held = [k for k in hdr.keys() if k != "__metadata__"]
+        except Exception:
+            held = []
+        verified, same = False, False
+        if held:
+            probe = held[0]
+            probe_dir = ctx.VOICES_DIR / ".parts" / _safe_id("base-probe", base_id)
+            try:
+                src = open_source(base_id)
+                pf = _fetch_tensor(src, probe, probe_dir)
+                fresh = Path(pf[1]).read_bytes() if pf[0] == "file" else bytes(pf[2])
+                with open(base_file, "rb") as f:
+                    f.seek(8 + hs + hdr[probe]["data_offsets"][0])
+                    have = f.read(hdr[probe]["data_offsets"][1] - hdr[probe]["data_offsets"][0])
+                verified, same = True, (fresh == have)
+            except SystemExit:
+                raise
+            except Exception:
+                verified, same = False, False
+            finally:
+                _cleanup_tmp(probe_dir)
+        if verified and not same:
+            _warn("  Base cache predates revision pinning and no longer matches HEAD — re-fetching.")
+            try:
+                base_file.unlink(missing_ok=True)
+            except Exception:
+                pass
+            _cache_base(base_id, base_file, base_json)
+        elif not verified:
+            _warn("  Base cache lineage unverified (offline?) — proceeding, mixed revisions possible.")
+    rev = _base_rev(base_id, base_file)
+    missing = _cache_validate(base_file, want)
+    if not missing:
+        return base_file
+    _step(f"Topping up base {base_id} ({len(missing)} tensor(s) missing)…")
+    try:
+        src = open_source(base_id, rev=rev)
+    except SystemExit:
+        raise
+    except Exception as e:
+        _fail(f"  ✗ Could not reach base {base_id} for top-up: {e}")
+    tmp_dir = ctx.VOICES_DIR / ".parts" / _safe_id("base", base_id)
+    staged = []
+    try:
+        for m in missing:
+            try:
+                fetched = _fetch_tensor(src, m, tmp_dir)
+            except (KeyError, ValueError) as e:
+                _fail(f"  ✗ Base {base_id} has no tensor '{m}'. Delta needs same names on both sides.")
+            kind, raw_path, data, dtype, shape = fetched
+            if _is_ggml_quant(dtype):
+                # quant blocks can't live in a .safetensors cache: dequant once to F32
+                f32 = src.read_f32(m)
+                staged.append((m, f32.astype("float32").tobytes(), "F32", tuple(int(x) for x in f32.shape), None))
+            elif kind == "file":
+                staged.append((m, None, dtype, tuple(int(x) for x in shape), raw_path))
+            else:
+                staged.append((m, bytes(data), dtype, tuple(int(x) for x in shape), None))
+    except SystemExit:
+        _cleanup_tmp(tmp_dir)
+        raise
+    try:
+        new_hdr = _cache_topup_write(base_file, staged)
+    except OSError as e:
+        _cleanup_tmp(tmp_dir)
+        _fail(f"  ✗ {e}")
+    _cleanup_tmp(tmp_dir)
+    # refresh base json with the full tensor list
+    try:
+        meta = {"source_hf_model": base_id, "revision": rev, "downloaded_at": _now_iso(),
+                "tensors": [{"name": k, "shape": list(v["shape"]), "dtype": v["dtype"]}
+                            for k, v in new_hdr.items() if k != "__metadata__"]}
+        jtmp = base_json.with_suffix(".tmp")
+        fd = os.open(str(jtmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, json.dumps(meta, indent=2).encode("utf-8") + b"\n")
+            try:
+                os.fsync(fd)
+            except Exception:
+                pass
+        finally:
+            os.close(fd)
+        try:
+            jtmp.replace(base_json)
+        except FileExistsError:
+            jtmp.unlink(missing_ok=True)
+    except Exception:
+        pass
+    return base_file
+
+
+def _cache_base(base_id, base_file, base_json):
+    _step(f"Caching base {base_id}…")
+    src = open_source(base_id)
+    names = src.names()
+    bname = _resolve_output_name(src, None, names)
+    if bname is None:
+        _fail(f"  ✗ Could not find the output tensor in base {base_id}.")
+    ref = src.ref(bname)
+    tmp_dir = ctx.VOICES_DIR / ".parts" / _safe_id("base", base_id)
+    fetched = _fetch_tensor(src, bname, tmp_dir)
+    # size now: _cleanup_tmp below deletes raw.bin before the metadata write
+    fetched_bytes = fetched[1].stat().st_size if fetched[0] == "file" else len(fetched[2])
+    _assert_not_symlink(base_file.parent if base_file.parent.exists() else base_file)
+    base_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(base_file.parent, 0o700)
+    except Exception:
+        pass
+    # avoid TOCTOU race if two processes cache same base
+    if base_file.exists():
+        _cleanup_tmp(tmp_dir)
+        return
+    tmp_st = base_file.parent / "base.tmp"
+    if fetched[0] == "file":
+        _write_safetensors_streaming(bname, str(fetched[1]), fetched[1].stat().st_size, fetched[3], fetched[4], str(tmp_st))
+    else:
+        write_safetensors({bname: (fetched[2], fetched[3], fetched[4])}, str(tmp_st))
+    try:
+        tmp_st.replace(base_file)
+    except FileExistsError:
+        tmp_st.unlink(missing_ok=True)
+    _cleanup_tmp(tmp_dir)
+    # atomic 0600 json
+    jtmp = base_json.with_suffix(".tmp")
+    fd = os.open(str(jtmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, json.dumps({
+            "source_hf_model": base_id, "tensor_name": bname, "dtype": fetched[3],
+            "shape": list(fetched[4]), "bytes": fetched_bytes,
+            "tensors": [{"name": bname, "shape": list(fetched[4]), "dtype": fetched[3]}],
+            "downloaded_at": _now_iso(),
+        }, indent=2).encode("utf-8") + b"\n")
+        try:
+            os.fsync(fd)
+        except Exception:
+            pass
+    finally:
+        os.close(fd)
+    try:
+        jtmp.replace(base_json)
+    except FileExistsError:
+        jtmp.unlink(missing_ok=True)
+
+
+def _load_safetensors_or_gguf_f32(path):
+    # Returns (tensors_dict, dtype_map) for delta math. Safetensors preferred (no dequant).
+    # GGUF quant falls back to full F32 dequant once (unavoidable, warn; efficient for <50MB tests).
+    try:
+        hdr, tens = read_safetensors(str(path))
+        return hdr, tens, False
+    except Exception:
+        pass
+    try:
+        src = open_source(str(path))
+        names = [n for n in src.names() if n != "delta.voice.marker"]
+        if not names:
+            raise ValueError("no tensors")
+        # Pick output head or first for delta math (single-tensor delta path).
+        tname = None
+        try:
+            arch, cfg = _source_arch(src)
+            tname = _resolve_output_name(src, cfg, names)
+        except Exception:
+            tname = None
+        if tname is None or tname not in names:
+            tname = names[0]
+        ref = src.ref(tname)
+        _warn(f"  {Path(path).name} is {ref.dtype} ({src.kind}) — dequanting once to F32 for delta math (unavoidable).")
+        arr = src.read_f32(tname)
+        # Build synthetic safetensors-like dict for chunked math below.
+        return {"__gguf_f32__": {"dtype": "F32", "shape": list(arr.shape), "_arr": arr}, tname: {"dtype": "F32", "shape": list(arr.shape), "_arr": arr}}, {tname: {"dtype": "F32", "shape": list(arr.shape)}}, True
+    except Exception as e:
+        raise ValueError(f"{path} is not a valid .safetensors or .gguf for delta: {e}")

vlib/cmds_misc.py

@@ -0,0 +1,550 @@
+"""Misc commands: list, info, remove, cleanup, auth, path, doctor."""
+
+from pathlib import Path
+import getpass
+import json
+import os
+import sys
+import textwrap
+import time
+import urllib.error
+import urllib.request
+from vlib import ctx
+from vlib.ui import _confirm, _fail, _noninteractive, _note, _ok, _say, _step, _term_width, _trunc, _warn
+from vlib.net import _get_hf_token, _hf_auth_headers
+from vlib.tensors import read_safetensors
+from vlib.sources import _base_paths
+from vlib.registry import _iter_voices, _read_meta, _registry_resolve, log_operation
+
+
+def cmd_list(args):
+    if getattr(args, "target", None) == "base" or getattr(args, "list_base", False):
+        _list_bases()
+        return
+
+    voices = [d for d in _iter_voices() if (d / "voice.json").exists()]
+    if not voices:
+        _say("  No voices stored yet.  Use 'voice get <model>' to save one.")
+        return
+
+    tw = _term_width()
+    w_name = 26 if tw >= 80 else max(14, tw - 54)
+    w_src = 40 if tw >= 80 else max(18, tw - w_name - 16)
+    w_type = 8
+    _say(f"  {_trunc('Name', w_name):<{w_name}} {_trunc('Source', w_src):<{w_src}} {_trunc('Type', w_type):<{w_type}}")
+    _say(f"  {'─'*w_name} {'─'*w_src} {'─'*w_type}")
+    for d in voices:
+        meta = _read_meta(d / "voice.json") or {}
+        name = meta.get("name", d.name)
+        src = meta.get("source_hf_model") or meta.get("source") or "—"
+        typ = meta.get("type", "voice")
+        _say(f"  {_trunc(name, w_name):<{w_name}} {_trunc(src, w_src):<{w_src}} {_trunc(typ, w_type):<{w_type}}")
+
+
+def _list_bases():
+    base_root = ctx.VOICES_DIR / "base"
+    if not base_root.exists() or not any(base_root.rglob("*.json")):
+        _say("  No bases cached yet.  Use 'voice delta <voice>' to fetch one.")
+        return
+    tw = _term_width()
+    w_base = 40 if tw >= 80 else max(20, tw - 30)
+    _say(f"  {_trunc('Base', w_base):<{w_base}} {'Bytes':<18} {'Fetched':<12}")
+    _say(f"  {'─'*w_base} {'─'*18} {'─'*12}")
+    seen = set()
+    for jpath in sorted(base_root.rglob("*.json")):
+        try:
+            meta = json.loads(jpath.read_text())
+        except Exception:
+            continue
+        parts = jpath.relative_to(base_root).parts
+        base_id = f"{parts[0]}/{Path(parts[1]).stem}" if len(parts) == 2 else f"{parts[0]}/{parts[1]}"
+        if base_id in seen:
+            continue
+        seen.add(base_id)
+        b = meta.get("bytes")
+        b_str = f"{b} ({b/1e6:.1f} MB)" if isinstance(b, int) else "—"
+        fetched = meta.get("downloaded_at", "—")[:10]
+        _say(f"  {_trunc(base_id, w_base):<{w_base}} {_trunc(b_str, 18):<18} {_trunc(fetched, 12):<12}")
+
+
+def _voice_tensors(meta):
+    """Normalize voice metadata to a (tensors, synthetic) pair.
+    Flat-only files (tensor_name/shape/dtype, no tensors list) become a
+    synthetic 1-entry list so readers share one code path."""
+    claims = meta.get("tensors")
+    if isinstance(claims, list) and claims:
+        return list(claims), False
+    if meta.get("tensor_name"):
+        return [{"name": meta.get("tensor_name"), "shape": meta.get("shape"),
+                 "dtype": meta.get("dtype")}], True
+    return [], False
+
+
+def _verify_voice_file(path, meta):
+    """Cross-check voice.json claims against the artifact's own header.
+    Returns warning strings (empty = agrees). Never raises: an unreadable
+    file is a note, not a failure."""
+    out = []
+    if str(path).endswith(".gguf"):
+        return out  # quant type names differ; nothing truthful to compare
+    try:
+        header, tens = read_safetensors(str(path))
+    except Exception:
+        return ["  ? Could not read the artifact header; showing voice.json as-is."]
+    names = [k for k in tens if k != "delta.voice.marker"]
+    claims, _synthetic = _voice_tensors(meta)
+    if claims:
+        for entry in claims:
+            tname = entry.get("name")
+            if tname not in tens:
+                out.append(f"  ! MISMATCH tensor: voice.json lists '{tname}', file doesn't hold it.")
+                continue
+            info = tens[tname]
+            claimed_shape = entry.get("shape")
+            if claimed_shape is not None and list(claimed_shape) != list(info["shape"]):
+                out.append(f"  ! MISMATCH shape '{tname}': voice.json says {list(claimed_shape)}, "
+                           f"file holds {list(info['shape'])} — file wins.")
+            claimed_dtype = (entry.get("dtype") or "").upper()
+            if claimed_dtype and claimed_dtype != str(info["dtype"]).upper():
+                out.append(f"  ! MISMATCH dtype '{tname}': voice.json says {entry.get('dtype')}, "
+                           f"file holds {info['dtype']} — file wins.")
+        claimed_names = {e.get("name") for e in claims}
+        for extra in names:
+            if extra not in claimed_names:
+                out.append(f"  ! File holds '{extra}' which voice.json doesn't list.")
+        if not names:
+            out.append("  ? No tensors found in the artifact.")
+        has_marker = "delta.voice.marker" in tens
+        if meta.get("type") == "delta" and not has_marker:
+            out.append("  ! voice.json claims delta but the file has no delta marker.")
+        if meta.get("type") != "delta" and has_marker:
+            out.append("  ! File carries a delta marker but voice.json type is "
+                       f"'{meta.get('type', 'voice')}'.")
+        return out
+    # No tensor claims at all (minimal legacy json): only the delta-marker
+    # check below is truthful; shape/dtype have nothing to compare against.
+    if not names:
+        return ["  ? No tensors found in the artifact."]
+    has_marker = "delta.voice.marker" in tens
+    if meta.get("type") == "delta" and not has_marker:
+        out.append("  ! voice.json claims delta but the file has no delta marker.")
+    if meta.get("type") != "delta" and has_marker:
+        out.append("  ! File carries a delta marker but voice.json type is "
+                   f"'{meta.get('type', 'voice')}'.")
+    return out
+
+
+def cmd_info(args):
+    voicename = args.voicename.strip()
+    voice_path, voice_meta = _registry_resolve(voicename)
+    if voice_path is None or not voice_path.exists():
+        bps = _base_paths(voicename)
+        if bps and bps[0].exists():
+            meta = _read_meta(bps[1]) or {}
+            _say(f"  Name:    {voicename}")
+            _say(f"  Type:    base")
+            _say(f"  Source:  https://huggingface.co/{meta.get('source_hf_model', voicename)}")
+            _say(f"  Tensor:  {meta.get('tensor_name', '—')}")
+            _say(f"  Shape:   {meta.get('shape', '—')}")
+            _say(f"  Dtype:   {meta.get('dtype', '—')}")
+            _say(f"  File:    {bps[0]}")
+            return
+        _fail(f"  ✗ Voice '{voicename}' not found. Try voice list")
+
+    meta = _read_meta(Path(voice_path).parent / "voice.json") or voice_meta or {}
+    name = meta.get("name", voicename)
+    source = meta.get("source_hf_model") or meta.get("source") or "—"
+    typ = meta.get("type", "voice")
+    _say(f"  Name:    {name}")
+    _say(f"  Type:    {typ}")
+    _say(f"  Source:  {source}")
+    if meta.get("family") or meta.get("architecture"):
+        _say(f"  Family:  {meta.get('family', '—')} ({meta.get('architecture', '—')})")
+    tensors, _synthetic = _voice_tensors(meta)
+    only = tensors[0] if len(tensors) == 1 else {}
+    _say(f"  Tensor:  {meta.get('tensor_name') or only.get('name', '—')}")
+    _say(f"  Shape:   {meta.get('shape') or only.get('shape', '—')}")
+    _say(f"  Dtype:   {meta.get('dtype') or only.get('dtype', '—')}")
+    if len(tensors) > 1:
+        for entry in tensors:
+            _say(f"    - {entry.get('name')}: {entry.get('shape')} · {entry.get('dtype')}")
+    b = meta.get("bytes")
+    if isinstance(b, int):
+        _say(f"  Bytes:   {b} ({b/1e6:.1f} MB)")
+    if meta.get("base"):
+        _say(f"  Base:    {meta.get('base')}")
+    if meta.get("license"):
+        _say(f"  License: {_trunc(meta['license'], 80)}")
+    _say(f"  Saved:   {meta.get('downloaded_at', meta.get('fetched_at', '—'))}")
+    _say(f"  File:    {voice_path}")
+    for w in _verify_voice_file(str(voice_path), meta):
+        _warn(w)
+
+
+def cmd_remove(args):
+    name = args.voice.strip().lower()
+    target = next((d for d in _iter_voices() if d.name.lower() == name), None)
+    if target is None:
+        _fail(f"  ✗ Voice '{args.voice}' not found.")
+    if _noninteractive(args) and not getattr(args, "yes", False):
+        _fail(f"  ✗ Refusing to remove '{target.name}' in non-interactive mode without --yes.")
+    if not _confirm(f"  Remove voice '{target.name}'? [y/N]: ", args):
+        _say("  Cancelled.")
+        sys.exit(0)
+    import shutil
+    shutil.rmtree(target)
+    log_operation({"op": "remove", "voice": target.name, "output": str(target), "status": "ok"})
+    _ok(f"Removed '{target.name}'.")
+
+
+def cmd_cleanup(args):
+    parts_dir = ctx.VOICES_DIR / ".parts"
+    if not parts_dir.exists() or not any(parts_dir.iterdir()):
+        _ok("No incomplete downloads to clean.")
+        return
+    removed, reclaimed = 0, 0
+    import shutil
+    force = bool(getattr(args, "force", False))
+    for p in sorted(parts_dir.iterdir()):
+        try:
+            if p.is_dir():
+                lock = p / ".lock"
+                if lock.exists() and not force:
+                    try:
+                        if time.time() - lock.stat().st_mtime < 600:
+                            _note(f"Skipping active download {p.name}")
+                            continue
+                    except Exception:
+                        pass
+                sz = sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
+                shutil.rmtree(p)
+                removed += 1
+                reclaimed += sz
+                _ok(f"Removed {p.name}/ ({sz/1e6:.1f} MB)")
+            else:
+                sz = p.stat().st_size if p.is_file() else 0
+                p.unlink()
+                removed += 1
+                reclaimed += sz
+                _ok(f"Removed {p.name}")
+        except Exception as e:
+            if ctx.VERBOSE:
+                _warn(f"Could not remove {p}: {e}")
+    _ok(f"Cleaned {removed} entry(s), reclaimed {reclaimed/1e6:.1f} MB.")
+    try:
+        if not any(parts_dir.iterdir()):
+            parts_dir.rmdir()
+    except Exception:
+        pass
+
+
+def cmd_auth(args):
+    tok_path = ctx.HF_TOKEN_PATH
+    if getattr(args, "clear", False):
+        try:
+            tok_path.unlink(missing_ok=True)
+            _ok("Removed stored HF token.")
+        except Exception as e:
+            _fail(f"  ✗ Could not remove token: {e}")
+        return
+    if getattr(args, "show", False):
+        tok = _get_hf_token()
+        if not tok:
+            _say("  ✓ No HF token stored. Run: voice auth")
+            return
+        masked = tok[:4] + "·" * (len(tok) - 8) + tok[-4:] if len(tok) > 8 else "·" * len(tok)
+        src = "environment" if os.environ.get("HF_TOKEN") or os.environ.get("HF_HUB_TOKEN") else str(tok_path)
+        _say(f"  ✓ HF token present: {masked} ({src})")
+        return
+    _say("  Paste your HF token (hf_…): it stays on this machine, 0600, never logged.")
+    try:
+        try:
+            tok = getpass.getpass("  Paste HF token: ").strip()
+        except Exception:
+            tok = input("  Paste HF token: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    if not tok:
+        _say("  ⚠ No token entered.")
+        sys.exit(0)
+    if not tok.startswith("hf_") or len(tok) < 10:
+        _fail("  ✗ That doesn't look like an HF token (should start with hf_…).")
+    _step("Verifying…")
+    try:
+        req = urllib.request.Request("https://huggingface.co/api/whoami-v2",
+                                     headers=_hf_auth_headers("https://huggingface.co/api/whoami-v2", {"Authorization": f"Bearer {tok}"}))
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read())
+            _ok(f"Verified as {data.get('name') or data.get('id') or 'ok'}.")
+    except urllib.error.HTTPError as e:
+        if e.code in (401, 403):
+            _fail("  ✗ Token rejected (401). Check it at https://huggingface.co/settings/tokens")
+        _warn(f"Verification skipped (HTTP {e.code}), saving anyway.")
+    except Exception:
+        _warn("Could not verify now — saving anyway.")
+    try:
+        ctx.VOICES_DIR.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(ctx.VOICES_DIR, 0o700)
+        except Exception:
+            pass
+        tmp = tok_path.with_suffix(".tmp")
+        # atomic 0600: create with restricted perms, avoid 0644 race
+        fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, (tok.strip() + "\n").encode("utf-8"))
+            try:
+                os.fsync(fd)
+            except Exception:
+                pass
+        finally:
+            os.close(fd)
+        try:
+            os.chmod(tmp, 0o600)
+        except Exception:
+            pass
+        tmp.replace(tok_path)
+        try:
+            os.chmod(tok_path, 0o600)
+        except Exception:
+            pass
+        _ok(f"Saved to {tok_path} (0600).")
+    except Exception as e:
+        _fail(f"  ✗ Could not save token: {e}")
+
+
+def cmd_path(_args):
+    script = _entry_script()
+    if script is None:
+        _fail("  ✗ Cannot locate the voice entry script in this interpreter. Run voice.py directly.")
+    script = Path(script).resolve()
+    vlib_src = script.parent / "vlib"
+    if sys.platform.startswith("win"):
+        import shutil as _sh
+        bindir = Path(os.environ.get("LOCALAPPDATA", "")) / "voice-cli"
+        if str(bindir) == "voice-cli":
+            _fail("  ✗ Couldn't find a Windows app-data folder to install into.")
+        bindir.mkdir(parents=True, exist_ok=True)
+        _copy_tree(vlib_src, bindir / "vlib")
+        _sh.copy2(str(script), str(bindir / "voice.py"))
+        if _sh.which("voice"):
+            _ok("Voice updated on your PATH.")
+        else:
+            _ok("Voice is ready. Add this to your PATH (PowerShell):")
+            _say(f'    setx PATH "%PATH%;{bindir}"')
+        return
+    import shutil
+    existing = shutil.which("voice")
+    if existing:
+        try:
+            same = Path(existing).resolve() == script
+        except Exception:
+            same = False
+        if same:
+            _ok("Voice is already on your PATH.")
+            return
+        # Stale install: relink only when the old entry is our symlink
+        # (points at a voice.py); never touch a foreign binary.
+        try:
+            old_target = os.readlink(existing)
+        except OSError:
+            _fail(f"  ✗ 'voice' on PATH isn't ours ({existing}). Remove or rename it, then retry.")
+        if Path(old_target).name != "voice.py":
+            _fail(f"  ✗ '{existing}' isn't a voice install (points at {old_target}). Remove or rename it, then retry.")
+        try:
+            Path(existing).unlink()
+            Path(existing).symlink_to(str(script))
+        except (PermissionError, OSError):
+            _fail(f"  ✗ Couldn't relink {existing}. Try: sudo ln -sf {script} {existing}")
+        _ok(f"Voice updated: {existing} now points at {script}. Open a new terminal and run: voice")
+        return
+    candidates = [Path("/usr/local/bin"), Path.home() / ".local" / "bin", Path("/usr/bin"), Path("/bin")]
+    on_path = next((d for d in candidates if d.is_dir() and str(d) in os.environ.get("PATH", "").split(":")), None)
+    if on_path is None:
+        _fail("  ✗ No writable directory on PATH found. Add one and retry.")
+    target = on_path / "voice"
+    try:
+        target.symlink_to(str(script))
+    except FileExistsError:
+        target.unlink()
+        target.symlink_to(str(script))
+    except (PermissionError, OSError):
+        _fail(f"  ✗ Couldn't create a link in {on_path}. Try: sudo ln -s {script} {target}")
+    _ok(f"Voice is ready at {target}. Open a new terminal and run: voice")
+
+
+def cmd_doctor(_args):
+    import platform
+    import shutil
+    _say(f"  voice {ctx.VERSION} — doctor")
+    _say(f"  Python {platform.python_version()} ({sys.executable})")
+    uv = shutil.which("uv")
+    _say(f"  uv {'found: ' + uv if uv else 'NOT FOUND — curl -LsSf https://astral.sh/uv/install.sh | sh'}")
+    venv = ctx.VOICES_DIR / ".venv"
+    if (venv / "bin" / "python").exists():
+        _say(f"  venv {venv} present")
+    else:
+        _say(f"  venv not created yet (created on first get/cast/pack/delta)")
+    try:
+        free = shutil.disk_usage(ctx.VOICES_DIR if ctx.VOICES_DIR.exists() else Path.home()).free
+        _say(f"  disk free {free/1e9:.1f} GB")
+    except Exception:
+        pass
+    tok = _get_hf_token()
+    _say(f"  HF token {'present' if tok else 'not present'}")
+    if ctx.OPERATIONS_LOG.exists():
+        try:
+            n = sum(1 for _ in open(ctx.OPERATIONS_LOG))
+            _say(f"  operations logged: {n} ({ctx.OPERATIONS_LOG})")
+        except Exception:
+            pass
+    if ctx.REPORTS_JSONL.exists():
+        try:
+            n = sum(1 for _ in open(ctx.REPORTS_JSONL))
+            pending = len(list(ctx.REPORTS_OUTBOX.glob("*.json"))) if ctx.REPORTS_OUTBOX.exists() else 0
+            _say(f"  reports: {n} local, {pending} pending in outbox ({ctx.REPORTS_JSONL})")
+            if pending > 5000:
+                _warn(f"  outbox >5000 pending — run: voice report --sync --yes")
+            # headroom
+            try:
+                sz = ctx.REPORTS_JSONL.stat().st_size
+                if sz > 50 * 1024 * 1024:
+                    _warn(f"  reports.jsonl {sz/1e6:.1f} MB — consider archiving")
+            except Exception:
+                pass
+        except Exception:
+            pass
+    else:
+        _say(f"  reports: none yet — run: voice report")
+    try:
+        req = urllib.request.Request("https://huggingface.co/api/whoami-v2" if tok else "https://huggingface.co",
+                                     headers=_hf_auth_headers("https://huggingface.co"))
+        with urllib.request.urlopen(req, timeout=3) as resp:
+            _say(f"  connectivity huggingface.co ok ({resp.status})")
+    except Exception as e:
+        _warn(f"connectivity failed: {e}")
+    # check push target
+    try:
+        _say(f"  community reports: {ctx.REPORTS_DATASET_ID} (share prompt on voice report)")
+    except Exception:
+        pass
+
+
+def _print_version():
+    import platform
+    _say(f"  voice {ctx.VERSION}")
+    _say(f"  Python {platform.python_version()} ({sys.executable})")
+    for mod in ("gguf", "numpy", "huggingface_hub", "hf_xet"):
+        try:
+            m = __import__(mod)
+            _say(f"  {mod} {getattr(m, '__version__', 'installed')}")
+        except Exception:
+            _say(f"  {mod} not installed")
+
+
+def _print_completion(shell):
+    cmds = ["get", "cast", "delta", "list", "info", "remove", "cleanup", "auth", "report", "path", "doctor"]
+    voices = [d.name for d in _iter_voices() if (d / "voice.json").exists()]
+    vlist = " ".join(voices)
+    clist = " ".join(cmds)
+    if shell == "bash":
+        print(textwrap.dedent(f"""\
+            _voice_completions() {{
+                local cur="${{COMP_WORDS[COMP_CWORD]}}"
+                local cmds="{clist}"
+                if [[ $COMP_CWORD -eq 1 ]]; then
+                    COMPREPLY=($(compgen -W "$cmds --help --version --completion" -- "$cur"))
+                    return
+                fi
+                case "${{COMP_WORDS[1]}}" in
+                    cast|delta|info|remove) COMPREPLY=($(compgen -W "{vlist}" -- "$cur")) ;;
+                    list) COMPREPLY=($(compgen -W "base --base" -- "$cur")) ;;
+                    *) COMPREPLY=() ;;
+                esac
+            }}
+            complete -F _voice_completions voice
+            """))
+    elif shell == "zsh":
+        print(textwrap.dedent(f"""\
+            #compdef voice
+            _voice() {{
+                local -a cmds; cmds=({clist})
+                local -a voices; voices=({vlist})
+                _arguments -C "1: :($cmds)" "*::arg:->args"
+                case $line[1] in
+                    cast|delta|info|remove) _describe voices voices ;;
+                    list) _values "target" base ;;
+                esac
+            }}
+            compdef _voice voice
+            """))
+    elif shell == "fish":
+        print(textwrap.dedent(f"""\
+            complete -c voice -f
+            complete -c voice -n "__fish_use_subcommand" -a "{clist}" -d "voice command"
+            complete -c voice -n "__fish_seen_subcommand_from cast delta info remove" -a "{vlist}"
+            """))
+
+
+def _copy_tree(src, dst):
+    """Refresh-copy a directory (Windows PATH install needs vlib/ beside voice.py)."""
+    import shutil as _sh
+    if Path(src).is_dir():
+        _sh.copytree(str(src), str(dst), dirs_exist_ok=True,
+                     ignore=_sh.ignore_patterns("__pycache__"))
+    return dst
+
+
+def _entry_script():
+    """Absolute path of the CLI entry (voice.py), or None if unknown.
+    The split moved commands into vlib/, so __file__ here is the module —
+    resolve via __main__ instead. Single seam for every entry-path need."""
+    _main = getattr(sys.modules.get("__main__"), "__file__", None)
+    if not _main:
+        return None
+    return os.path.realpath(_main)
+
+
+def _ensure_venv(cmd):
+    if os.environ.get("VOICE_NO_VENV") in ("1", "true", "True"):
+        return
+    if cmd not in ("get", "cast", "delta"):
+        return
+    venv = ctx.VOICES_DIR / ".venv"
+    venv_py = venv / "bin" / "python"
+    try:
+        if venv_py.exists() and (sys.prefix == str(venv) or Path(sys.executable).resolve().parent.parent == venv.resolve()):
+            return
+    except Exception:
+        pass
+    import shutil
+    if shutil.which("uv") is None:
+        _fail("  ✗ uv not found. Install it, then retry:\n    curl -LsSf https://astral.sh/uv/install.sh | sh")
+    if venv_py.exists():
+        try:
+            _main = _entry_script()
+            if not _main:
+                _warn(" venv re-exec skipped: entry script unknown, continuing in-process.")
+                return
+            os.execv(str(venv_py), [str(venv_py), _main, *sys.argv[1:]])
+        except Exception as e:
+            if ctx.VERBOSE:
+                _warn(f"could not re-exec into venv: {e}")
+            return
+    _step(f"Creating a virtual environment at {venv}…")
+    import subprocess
+    try:
+        subprocess.run(["uv", "venv", str(venv), "--python", sys.executable], capture_output=True, check=True)
+        subprocess.run(["uv", "pip", "install", "--quiet", "--python", str(venv_py),
+                        "gguf", "numpy", "huggingface_hub[hf_xet]", "hf_xet"], capture_output=True, check=True)
+    except Exception as e:
+        _fail(f"  ✗ Failed to create venv: {e}")
+    _main = _entry_script()
+    if not _main:
+        _warn(" venv re-exec skipped: entry script unknown, continuing in-process.")
+        return
+    try:
+        os.execv(str(venv_py), [str(venv_py), _main, *sys.argv[1:]])
+    except Exception as e:
+        _fail(f"  ✗ Could not re-exec into venv: {e}")

vlib/cmds_voices.py

@@ -0,0 +1,551 @@
+"""Voice commands: get, cast, delta, add."""
+
+from pathlib import Path
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from vlib import ctx
+from vlib.ui import _fail, _noninteractive, _note, _now_iso, _ok, _say, _step
+from vlib.net import _cleanup_tmp, _safe_id
+from vlib.tensors import _is_delta_safetensors, _is_gguf_file, read_safetensors, write_safetensors
+from vlib.sources import _NAME_RULES, _base_paths, _family, _hf_license, _nested, _public_source, _sanitize_voice_name, _slugify_voice_name, open_source
+from vlib.fetch import _fetch_pack, _fetch_tensor, _resolve_output_name, _source_arch, _write_fetched, _write_voicepack_json
+from vlib.registry import _assert_not_symlink, _check_overwrite, _out_path, _read_meta, _registry_folder, _registry_name_exists, _registry_resolve, _resolve_name, _write_voice, log_operation
+from vlib.cache import _ensure_base_tensors
+from vlib.compute import _cast_core, _cast_pack, _load_tensor, _load_voice, _parse_exclude_list, _parse_tensor_list, _resolve_one_tensor, _tensor_src_meta
+from vlib.delta import _choose_voice, _compute_delta, _resolve_base
+
+
+def cmd_get(args):
+    source_id = args.source.strip().rstrip("/")
+    if not source_id:
+        _fail("  ✗ Enter a model name — for example: voice get google/gemma-3-1b")
+    _step(f"Finding the voice in {source_id}…")
+
+    try:
+        source = open_source(source_id)
+        names = source.names()
+        if not names:
+            _fail(f"  ✗ No tensors found in '{source_id}'.")
+        arch, config = _source_arch(source)
+        requested = _parse_tensor_list(args)
+        want_multi = bool(getattr(args, "multi", False)) or len(requested) > 1
+        if not requested and not want_multi:
+            tname = _resolve_output_name(source, config, names)
+            if tname is None:
+                _fail(f'  ✗ "{source_id}" doesn\'t expose an output head. Try `voice get {source_id} <tensor>` with a specific tensor.')
+            requested = [tname]
+        elif not requested and want_multi:
+            _fail("  ✗ --multi needs tensor names (pass them as positionals).")
+        resolved = [_resolve_one_tensor(r, names) for r in requested]
+        # Dedupe preserve order.
+        seen = set()
+        uniq = []
+        for r in resolved:
+            if r not in seen:
+                seen.add(r)
+                uniq.append(r)
+        resolved = uniq
+    except urllib.error.HTTPError as e:
+        _fail(f"  ✗ Model '{source_id}' was not found or is not accessible ({e.code}).")
+    except Exception as e:
+        if ctx.VERBOSE:
+            import traceback
+            _say(traceback.format_exc())
+        _fail(f"  ✗ Could not reach the model. Check your connection ({type(e).__name__}).")
+
+    if want_multi or len(resolved) > 1:
+        # Multi-pack -> voicepack.safetensors + voicepack.json (file output, not the registry).
+        if getattr(args, "name", None):
+            _fail("  ✗ --name is for registry voices; packs save to files. Drop --name or the extra tensors.")
+        out = Path(getattr(args, "out", None) or (Path.cwd() / "voicepack.safetensors"))
+        out.parent.mkdir(parents=True, exist_ok=True)
+        _check_overwrite(str(out), args)
+        pack = _fetch_pack(source, source_id, resolved)
+        _step(f"Packing {len(pack)} tensors → {out.name}…")
+        write_safetensors(pack, str(out))
+        _write_voicepack_json(out, source_id, pack)
+        log_operation({"op": "tensor_get", "source": source_id, "format": source.kind,
+                       "tensors": list(pack.keys()), "output": str(out), "status": "ok"})
+        _ok(f"Done → {out} ({len(pack)} tensors)")
+        return
+
+    # Single tensor from here.
+    tname = resolved[0]
+    ref = source.ref(tname)
+    if getattr(args, "out", None):
+        # Standalone file; --name has no meaning here.
+        if getattr(args, "name", None):
+            _fail("  ✗ --name is for registry voices; --out writes a standalone file. Drop one.")
+        out = Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        _check_overwrite(str(out), args)
+        _step(f"Extracting {tname} ({ref.dtype} {tuple(ref.shape)})…")
+        tmp_dir = ctx.VOICES_DIR / ".parts" / _safe_id(source_id, tname)
+        try:
+            fetched = _fetch_tensor(source, tname, tmp_dir)
+        except Exception as e:
+            _fail(f"  ✗ Could not extract tensor: {e}")
+        actual_out = _write_fetched(fetched, tname, out)
+        _cleanup_tmp(tmp_dir)
+        log_operation({"op": "tensor_get", "source": source_id, "format": source.kind, "tensor": tname,
+                       "dtype": fetched[3], "shape": list(fetched[4]), "output": str(actual_out), "status": "ok"})
+        _ok(f"Done → {actual_out}")
+        return
+
+    if ctx.VERBOSE:
+        _note(f"{_family(arch)} · {tname} · {ref.dtype} · {ref.shape}")
+
+    # name the voice
+    default_name = source_id.split("/")[-1].split("@")[0].split(":")[0].replace(".gguf", "").replace(".safetensors", "")
+    name = _resolve_name(args, default_name)
+    folder = _registry_folder(name)
+    if _registry_name_exists(name) and folder.exists() and ((folder / "voice.safetensors").exists() or (folder / "voice.gguf").exists()):
+        _check_overwrite(str(folder), args)
+
+    _step(f"Downloading {tname}…")
+    tmp_dir = ctx.VOICES_DIR / ".parts" / _safe_id(source_id, tname)
+    try:
+        fetched = _fetch_tensor(source, tname, tmp_dir)
+    except urllib.error.HTTPError as e:
+        _fail(f"  ✗ Could not download the tensor ({e.code}). Check your connection.")
+    except Exception as e:
+        if ctx.VERBOSE:
+            import traceback
+            _say(traceback.format_exc())
+        _fail(f"  ✗ Could not download the tensor: {e}")
+
+    vocab = _nested(config, "vocab_size") if config else None
+    hidden = _nested(config, "hidden_size", "n_embd") if config else None
+    license_text = None if getattr(args, "quiet", False) else (_hf_license(getattr(source, "repo", None)) if getattr(source, "repo", None) else None)
+
+    meta = {
+        "name": name,
+        "source": _public_source(source_id),
+        "source_format": source.kind,
+        "tensor_name": tname,
+        "tensors": [{"name": tname, "shape": list(fetched[4]), "dtype": fetched[3]}],
+        "vocab_size": vocab,
+        "hidden_dim": hidden,
+        "dtype": fetched[3],
+        "shape": list(fetched[4]),
+        "architecture": arch,
+        "family": _family(arch),
+        "license": license_text,
+        "downloaded_at": _now_iso(),
+    }
+    _write_voice(folder, tname, fetched, meta)
+    _cleanup_tmp(tmp_dir)
+
+    log_operation({"op": "get", "source": source_id, "format": source.kind, "tensor": tname,
+                   "dtype": fetched[3], "shape": list(fetched[4]), "output": str(folder), "status": "ok"})
+    _ok("Done. Your new voice is ready.")
+    _say(f"  Saved to: {folder}")
+    _say(f"  Use it:   voice cast <your-model.gguf> {name}")
+
+
+def cmd_cast(args):
+    target = args.target
+    if not os.path.exists(target):
+        _fail(f'  ✗ "{target}" couldn\'t be found.')
+    if os.path.isdir(target):
+        _fail(f'  ✗ "{target}" is a folder, not a model file.')
+
+    voice_arg = args.voice
+    voice_path, voice_meta = _registry_resolve(voice_arg)
+    if voice_path is None or not voice_path.exists():
+        _fail(f"  ✗ Voice '{voice_arg}' not found. Use 'voice list' or pass a .safetensors/.gguf path.")
+
+    target_format = "gguf" if _is_gguf_file(target) else "safetensors"
+    out_path = _out_path(args, target, voice_arg)
+    _check_overwrite(out_path, args)
+    # Voicepack in the registry (or a pack path): cast every tensor, not just the first.
+    try:
+        _probe = open_source(str(voice_path))
+        _pack_names = [n for n in _probe.names() if n != "delta.voice.marker"]
+    except Exception:
+        _pack_names = []
+    requested = _parse_tensor_list(args)
+    excludes = _parse_exclude_list(args)
+    if requested:
+        # Tensor filter: resolve each positional (exact or single substring), then cast the selection.
+        resolved = [_resolve_one_tensor(r, _pack_names) for r in requested]
+        seen = set()
+        selected = []
+        for r in resolved:
+            if r not in seen:
+                seen.add(r)
+                selected.append(r)
+        resolved_ex = set()
+        for e in excludes:
+            if e in _pack_names:
+                resolved_ex.add(e)
+            elif len([n for n in _pack_names if e in n]) == 1:
+                resolved_ex.add([n for n in _pack_names if e in n][0])
+        selected = [n for n in selected if n not in resolved_ex]
+        if not selected:
+            _fail("  ✗ --exclude removes all selected tensors. Nothing to cast.")
+        if len(selected) > 1:
+            _cast_pack(target, str(voice_path), out_path, args, op="cast",
+                       excludes=[n for n in _pack_names if n not in selected], meta=voice_meta)
+            return
+        f32, ref, raw, qtype = _load_tensor(str(voice_path), selected[0])
+        src_meta = voice_meta if voice_meta is not None else _tensor_src_meta(str(voice_path))
+        _cast_core(target, target_format, out_path, f32, ref, src_meta, args, op="cast", vraw=raw, vqtype=qtype)
+        return
+    if len(_pack_names) > 1:
+        _cast_pack(target, str(voice_path), out_path, args, op="cast", excludes=excludes, meta=voice_meta)
+        return
+
+    # auto-detect delta file via marker even without voice.json (e.g. shipped style.safetensors)
+    # do this after _check_overwrite so prompt and Detected don't interleave
+    if (voice_meta is None or voice_meta.get("type") != "delta") and voice_path.is_file():
+        try:
+            if _is_delta_safetensors(str(voice_path)):
+                voice_meta = {"type": "delta", "source": str(voice_path)}
+                _note("Detected delta voice — fusing style (delta + head)…")
+        except Exception:
+            pass
+
+    vf32, vref, vraw, vqtype = _load_voice(voice_path)
+    _cast_core(target, target_format, out_path, vf32, vref, voice_meta, args, op="cast", vraw=vraw, vqtype=vqtype)
+
+
+
+
+def cmd_delta(args):
+    import numpy as np
+
+    voicename = getattr(args, "voicename", None)
+    if not voicename or not str(voicename).strip():
+        voicename = _choose_voice(args)
+    voicename = voicename.strip()
+    # If voicename is an existing file/dir path, treat as direct voice file (e.g. /path/to/voice.safetensors)
+    _voice_file_mode = False
+    _voice_file_path = None
+    _candidate = Path(voicename).expanduser()
+    if _candidate.exists():
+        if _candidate.is_file():
+            _voice_file_mode = True
+            _voice_file_path = _candidate.resolve()
+            # derive default name: if file is inside ~/.voices/, use the voice folder name (e.g. ~/.voices/styletune-v2/voice.safetensors -> styletune-v2)
+            # otherwise use file stem. This lets delta-voice be named delta-<voice-name> when source is from registry
+            try:
+                is_inside_voices = str(_candidate.resolve()).startswith(str(ctx.VOICES_DIR.resolve()) + os.sep)
+            except Exception:
+                is_inside_voices = False
+            if is_inside_voices:
+                # e.g. ~/.voices/styletune-v2/voice.safetensors -> styletune-v2
+                raw = _candidate.parent.name
+                # if parent is base/ org dir, fallback to stem
+                if raw in ("base", ".voices") or raw.startswith("."):
+                    raw = _candidate.stem
+            else:
+                raw = _candidate.stem
+            # prompt for delta name, default is raw (or voice.json name if available)
+            try:
+                meta_tmp = _read_meta(_candidate.parent / "voice.json")
+                default_raw = (meta_tmp or {}).get("name") or raw
+            except Exception:
+                default_raw = raw
+            default_raw = str(default_raw).strip() or raw
+            # ask user for name, default from meta or file
+            if _noninteractive(args):
+                sanitized = _sanitize_voice_name(default_raw) or _slugify_voice_name(default_raw)
+            else:
+                try:
+                    prompt = f"  Name the delta or press enter to use [{default_raw}]: "
+                    entered = input(prompt).strip()
+                    chosen = entered or default_raw
+                    sanitized = _sanitize_voice_name(chosen) or _slugify_voice_name(chosen)
+                except (EOFError, KeyboardInterrupt):
+                    _say("  ⚠ Cancelled.")
+                    sys.exit(0)
+            if sanitized is None:
+                sanitized = "voice"
+            # keep original path for _compute_delta, but use sanitized name for delta naming / messages
+            voice_path = _voice_file_path
+            voice_meta = _read_meta(_candidate.parent / "voice.json")
+            # use sanitized as voicename for delta naming downstream (without delta- prefix, added later)
+            voicename = sanitized
+        elif _candidate.is_dir():
+            voice_path, voice_meta = _registry_resolve(str(_candidate))
+            if voice_path is None or not voice_path.exists():
+                _fail(f"  ✗ Voice '{voicename}' not found. Try voice list")
+            # use directory name as voicename if it looks like a voice folder
+            dir_name = _candidate.name
+            if _sanitize_voice_name(dir_name.replace("delta-", "", 1) if dir_name.lower().startswith("delta-") else dir_name) is not None:
+                voicename = dir_name
+            # fall through to existing meta handling
+        else:
+            # exists but not file/dir? treat as registry name
+            if "/" in voicename or "\\" in voicename or "." in voicename or _sanitize_voice_name(voicename.replace("delta-", "", 1) if voicename.lower().startswith("delta-") else voicename) is None:
+                _fail("  ✗ Invalid voice name. Use letters, numbers, hyphens, underscores.")
+            voice_path, voice_meta = _registry_resolve(voicename)
+            if voice_path is None or not voice_path.exists():
+                _fail(f"  ✗ Voice '{voicename}' not found. Try voice list")
+    else:
+        if "/" in voicename or "\\" in voicename or "." in voicename or _sanitize_voice_name(voicename.replace("delta-", "", 1) if voicename.lower().startswith("delta-") else voicename) is None:
+            _fail("  ✗ Invalid voice name. Use letters, numbers, hyphens, underscores.")
+        voice_path, voice_meta = _registry_resolve(voicename)
+        if voice_path is None or not voice_path.exists():
+            _fail(f"  ✗ Voice '{voicename}' not found. Try voice list")
+    # handle file-mode delta naming already set; for registry mode voice_path/voice_meta already resolved
+    if _voice_file_mode:
+        # voice_path already set, ensure it exists
+        if not voice_path.exists():
+            _fail(f"  ✗ Voice file '{_voice_file_path}' not found.")
+    else:
+        # registry mode already validated above
+        pass
+
+    source_hf = (voice_meta or {}).get("source_hf_model") or (voice_meta or {}).get("source") or "—"
+    _say(f"  '{voicename}' is {source_hf}")
+
+    # --base may be an HF repo (org/model) or a local file/dir path (e.g. /path/to/lm_head.safetensors)
+    base_arg = getattr(args, "base", None)
+    base_is_local = False
+    base_file = None
+    base_json = None
+    base_id = None
+    if base_arg and Path(base_arg).expanduser().exists():
+        p = Path(base_arg).expanduser().resolve()
+        if p.is_file():
+            base_file = p
+            base_id = str(p)
+            base_is_local = True
+        elif p.is_dir():
+            # directory containing model.safetensors or any safetensors
+            cand = p / "model.safetensors"
+            if cand.exists():
+                base_file = cand.resolve()
+                base_is_local = True
+                base_id = str(base_file)
+            else:
+                safes = sorted(p.glob("*.safetensors"))
+                if safes:
+                    base_file = safes[0].resolve()
+                    base_is_local = True
+                    base_id = str(base_file)
+                else:
+                    _fail(f"  ✗ No .safetensors found in {p}")
+        # if local, no base_json needed; will be used directly
+    if not base_is_local:
+        base_id = _resolve_base(args, source_hf)
+        # _resolve_base may return a local path if user typed a path at the prompt
+        _maybe_local = Path(str(base_id)).expanduser()
+        if _maybe_local.exists():
+            p = _maybe_local.resolve()
+            if p.is_file():
+                base_file = p
+                base_is_local = True
+                base_json = None
+            elif p.is_dir():
+                cand = p / "model.safetensors"
+                if cand.exists():
+                    base_file = cand.resolve()
+                    base_is_local = True
+                    base_id = str(base_file)
+                    base_json = None
+                else:
+                    safes = sorted(p.glob("*.safetensors"))
+                    if safes:
+                        base_file = safes[0].resolve()
+                        base_is_local = True
+                        base_id = str(base_file)
+                        base_json = None
+                    else:
+                        _fail(f"  ✗ No .safetensors found in {p}")
+        if not base_is_local:
+            tmp = _base_paths(base_id)
+            if tmp is None:
+                _fail(f"  ✗ Invalid base '{base_id}'")
+            base_file, base_json = tmp
+            try:
+                _vsrc = open_source(str(voice_path))
+                _need = [n for n in _vsrc.names() if n != "delta.voice.marker"]
+            except Exception:
+                _need = []
+            if not _need:
+                _fail("  ✗ No tensors found for delta.")
+            base_file = _ensure_base_tensors(base_id, _need, args)
+
+    delta_name = f"delta-{voicename.lower()}"
+    delta_folder = ctx.VOICES_DIR / delta_name
+    if delta_folder.exists() and ((delta_folder / "voice.safetensors").exists() or (delta_folder / "voice.gguf").exists()):
+        _check_overwrite(str(delta_folder), args)
+
+    _step("Crafting your style…")
+    _compute_delta(voice_path, base_file, delta_folder, delta_name, args)
+
+    meta = {
+        "name": delta_name, "type": "delta", "source": voicename,
+        "source_hf_model": _public_source(source_hf),
+        "base": _public_source(base_id),
+        "dtype": "F16",
+        "downloaded_at": _now_iso(),
+    }
+    # enrich with shape/dtype from the delta file (all tensors, not just the first)
+    try:
+        hdr, tens = read_safetensors(str(delta_folder / "voice.safetensors"))
+        keys = [k for k in tens.keys() if k != "delta.voice.marker"]
+        meta["tensors"] = [{"name": k, "shape": list(tens[k]["shape"]), "dtype": tens[k]["dtype"],
+                            "bytes": tens[k]["data_offsets"][1] - tens[k]["data_offsets"][0]} for k in keys]
+        if len(keys) == 1:
+            # backward compat: single-tensor voices keep flat fields
+            meta["tensor_name"] = keys[0]
+            meta["shape"] = list(tens[keys[0]]["shape"])
+            meta["dtype"] = tens[keys[0]]["dtype"]
+            meta["bytes"] = tens[keys[0]]["data_offsets"][1]
+    except Exception:
+        pass
+    jtmp = delta_folder / "voice.json.tmp"
+    jtmp.write_text(json.dumps(meta, indent=2) + "\n")
+    jtmp.replace(delta_folder / "voice.json")
+
+    log_operation({"op": "delta", "voice": voicename, "base": base_id, "tensor": meta.get("tensor_name"),
+                   "dtype": meta.get("dtype"), "shape": meta.get("shape"), "output": str(delta_folder), "status": "ok"})
+    _ok(f"Done → {delta_folder}")
+    _say(f"  Use it: voice cast <your-model.gguf> {delta_name}")
+
+
+def cmd_add(args):
+    import shutil
+    st_path = Path(getattr(args, "safetensors", "") or "").expanduser()
+    js_path = Path(getattr(args, "json", "") or "").expanduser()
+    if not st_path.is_file():
+        _fail(f'  ✗ "{st_path}" couldn\'t be found. Need voice.safetensors')
+    if not js_path.is_file():
+        _fail(f'  ✗ "{js_path}" couldn\'t be found. Need voice.json — both are required')
+    # validate safetensors
+    try:
+        hdr, tens = read_safetensors(str(st_path))
+    except Exception as e:
+        _fail(f"  ✗ {st_path} is not a valid .safetensors file: {e}")
+    if not tens:
+        _fail(f"  ✗ No tensors found in {st_path}")
+    # validate json
+    try:
+        meta = json.loads(js_path.read_text(encoding="utf-8"))
+    except Exception as e:
+        _fail(f"  ✗ {js_path} is not valid JSON: {e}")
+    if not isinstance(meta, dict):
+        _fail(f"  ✗ {js_path} must contain a JSON object")
+    # determine name: --name > json name > prompt
+    default_name = (meta.get("name") or st_path.stem or "voice").strip()
+    # sanitize default for display
+    name_arg = getattr(args, "name", None)
+    if name_arg and str(name_arg).strip():
+        name = str(name_arg).strip()
+    elif _noninteractive(args):
+        name = default_name
+    else:
+        try:
+            # show default from json
+            prompt = f"  Name the voice or press enter to use [{default_name}]: "
+            entered = input(prompt).strip()
+            name = entered or default_name
+        except (EOFError, KeyboardInterrupt):
+            _say("  ⚠ Cancelled.")
+            sys.exit(0)
+    if _sanitize_voice_name(name) is None:
+        _fail(f"  ✗ Invalid name '{name}'. {_NAME_RULES}")
+    folder = _registry_folder(name)
+    if _registry_name_exists(name) and folder.exists() and ((folder / "voice.safetensors").exists() or (folder / "voice.gguf").exists()):
+        _check_overwrite(str(folder), args)
+        # remove old to allow replace
+        try:
+            shutil.rmtree(folder)
+        except Exception:
+            pass
+    # also handle case where folder exists as partial
+    _assert_not_symlink(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(folder, 0o700)
+    except Exception:
+        pass
+    _assert_not_symlink(folder)
+    # copy files atomically with 0600 and fsync — tensor FIRST, then metadata,
+    # so a crash never leaves a valid voice.json pointing at a partial artifact.
+    dest_st = folder / "voice.safetensors"
+    dest_js = folder / "voice.json"
+    # ensure meta name matches sanitized folder name (lowercased)
+    meta = dict(meta)
+    meta["name"] = name.strip().lower() if _sanitize_voice_name(name) else name
+    # copy safetensors atomically: use tmp + fsync + replace, 0600
+    tmp_st = dest_st.with_suffix(".tmp")
+    # stream copy with fsync
+    with open(st_path, "rb") as src, open(tmp_st, "wb") as dst:
+        # ensure 0600
+        try:
+            os.chmod(tmp_st, 0o600)
+        except Exception:
+            pass
+        while True:
+            b = src.read(8 << 20)
+            if not b:
+                break
+            dst.write(b)
+        dst.flush()
+        try:
+            os.fsync(dst.fileno())
+        except Exception:
+            pass
+    try:
+        os.chmod(tmp_st, 0o600)
+    except Exception:
+        pass
+    tmp_st.replace(dest_st)
+    try:
+        os.chmod(dest_st, 0o600)
+    except Exception:
+        pass
+    # verify tensor before writing metadata
+    try:
+        rhdr, rtens = read_safetensors(str(dest_st))
+        if not rtens:
+            try:
+                dest_st.unlink(missing_ok=True)
+            except Exception:
+                pass
+            _fail(f"  ✗ No tensors found in {st_path} — nothing added.")
+    except SystemExit:
+        raise
+    except Exception as e:
+        try:
+            dest_st.unlink(missing_ok=True)
+        except Exception:
+            pass
+        _fail(f"  ✗ Validation failed for {st_path}: {e} — nothing added.")
+    # write json atomically 0600 (only after the tensor is known good)
+    tmp_js = dest_js.with_suffix(".json.tmp")
+    fd = os.open(str(tmp_js), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, (json.dumps(meta, indent=2) + "\n").encode("utf-8"))
+        try:
+            os.fsync(fd)
+        except Exception:
+            pass
+    finally:
+        os.close(fd)
+    try:
+        os.chmod(tmp_js, 0o600)
+    except Exception:
+        pass
+    tmp_js.replace(dest_js)
+    try:
+        dirfd = os.open(str(folder), os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+    log_operation({"op": "add", "source_st": str(st_path), "source_json": str(js_path), "output": str(folder), "status": "ok"})
+    _ok(f"Added voice '{name}' → {folder}")
+    _say(f"  File: {dest_st} ({dest_st.stat().st_size/1e6:.1f} MB)")
+    _say(f"  Use it: voice cast <your-model.gguf> {name}")

vlib/compute.py

@@ -0,0 +1,1186 @@
+"""Cast math: orient, fuse, quantize, pack writes."""
+
+from pathlib import Path
+import os
+import struct
+import sys
+import time
+from vlib import ctx
+from vlib.ui import _confirm, _fail, _noninteractive, _note, _ok, _progress_pref, _say, _step, _transform, _warn
+from vlib.tensors import _gguf_raw_to_f32, _is_delta_safetensors, _is_ggml_quant, _is_gguf_file, _safetensors_write_repl, decode_to_f32, encode_from_f32, read_safetensors, rewrite_safetensors_tensor
+from vlib.sources import OUTPUT_ALIASES, _nested, detect_output_tensor, largest_2d, open_source
+from vlib.registry import log_operation
+
+
+def _load_voice(voice_path):
+    """Load a voice artifact. Returns (f32_array_or_None, ref, raw_bytes_or_None, ggml_type_or_None).
+    Quantized GGUF artifacts carry raw blocks; safetensors artifacts decode to f32."""
+    src = open_source(str(voice_path))
+    names = [n for n in src.names() if n != "delta.voice.marker"]
+    if not names:
+        _fail(f"  ✗ No tensors found in {voice_path}.")
+    tname = names[0] if len(names) == 1 else "output.weight" if "output.weight" in names else names[0]
+    ref = src.ref(tname)
+    if src.kind == "gguf" and _is_ggml_quant(ref.dtype):
+        return None, ref, src.read_raw(tname), ref.dtype
+    return src.read_f32(tname), ref, None, None
+
+
+def _orient(arr, shape, target_shape):
+    import numpy as np
+    if tuple(shape) == tuple(target_shape):
+        return arr
+    if tuple(shape) == tuple(target_shape[::-1]):
+        if ctx.VERBOSE:
+            _note("Transposing to match the target layout…")
+        return np.ascontiguousarray(arr.T)
+    return None
+
+
+def _cast_st_prepare(target, tensors, vf32, vref, meta, args, vraw=None, vqtype=None, strict_target=False, target_name=None):
+    """Per-tensor compute for a safetensors target. Returns (tname, data, tdtype, tshape).
+    target_name (from _resolve_pack_targets) overrides lookup; None keeps the
+    original single-tensor behavior byte-for-byte."""
+    import numpy as np
+    if vraw is not None:
+        # quant artifact -> safetensors target: dequant is the only requant path
+        from gguf.constants import GGMLQuantizationType as Q
+        from gguf.quants import quant_shape_to_byte_shape
+        vf32 = _gguf_raw_to_f32(vraw, Q[vqtype], tuple(reversed(tuple(int(x) for x in vref.shape))))
+    names = list(tensors.keys())
+    if target_name is not None:
+        tname = target_name if target_name in names else None
+        if tname is None:
+            _fail(f"  ✗ Resolved target '{target_name}' for '{vref.name}' not in {target}.")
+    else:
+        tname = vref.name if vref.name in names else None
+        if tname is None and strict_target:
+            _fail(f"  ✗ Tensor '{vref.name}' not found in target {target}. Voicepack requires exact match (not mapping to another tensor).")
+    if tname is None:
+        tname = detect_output_tensor(names, None) or largest_2d(names, {n: tensors[n]["shape"] for n in names})
+    if tname is None:
+        _fail("  ✗ Could not find a matching tensor in the target.")
+    tshape = tuple(tensors[tname]["shape"])
+    tdtype = tensors[tname]["dtype"]
+    # --quant override for safetensors target: only F32/F16/BF16/keep/target make sense (no GGUF quants).
+    _qo = _parse_quant_override(getattr(args, "quant", None) or "keep")
+    if _qo is None:
+        _fail(f"  ✗ Invalid --quant '{getattr(args, 'quant', None)}' for safetensors target. Use keep|target|f32|f16|bf16.")
+    if _qo not in ("keep", "target", "f32", "f16", "bf16"):
+        _fail(f"  ✗ --quant {_qo} needs GGUF target (safetensors has no quant {_qo}). Use keep|target|f32|f16|bf16.")
+    if _qo in ("f32", "f16", "bf16"):
+        _want = {"f32": "F32", "f16": "F16", "bf16": "BF16"}[_qo]
+        if _want != tdtype.upper():
+            _warn(f"  Re-encoding target {tdtype} → {_want} for --quant {_qo} (extra conversion).")
+            tdtype = _want
+    # Show quant/target by default for tensor commands (advanced) and verbose for voice.
+    try:
+        _svq = vqtype if vraw is not None else vref.dtype
+    except Exception:
+        _svq = "?"
+    if ctx.VERBOSE:
+        _note(f"Voice '{vref.name}' is {_svq} {tuple(vref.shape)} → target '{tname}' is {tdtype} {tshape}")
+    if vraw is not None and ctx.VERBOSE:
+        _note(f"Dequanting {vqtype} once to F32 for safetensors target (unavoidable, safetensors has no quant).")
+    oriented = _orient(vf32, vref.shape, tshape)
+    if oriented is None:
+        _fail(f"  ✗ Voice shape {vref.shape} doesn't fit target tensor {tname} {tshape}.")
+    if (meta or {}).get("type") == "delta":
+        _step(f"Fusing style into {tname} (delta + head → {tdtype}, kept)…")
+        with open(target, "rb") as f:
+            _hs = struct.unpack("<Q", f.read(8))[0]
+        info = tensors[tname]
+        with open(target, "rb") as f:
+            f.seek(8 + _hs + info["data_offsets"][0])
+            head_f32 = decode_to_f32(f.read(info["data_offsets"][1] - info["data_offsets"][0]), tdtype, tshape)
+        oriented = np.ascontiguousarray(head_f32 + oriented)
+    data = encode_from_f32(oriented, tdtype)
+    return tname, data, tdtype, tshape
+
+
+def _cast_core(target, target_format, out_path, vf32, vref, meta, args, op="cast", vraw=None, vqtype=None, strict_target=False):
+    if getattr(args, "speak", False) and target_format != "gguf":
+        _fail("  ✗ --speak needs a .gguf target.")
+    if target_format == "gguf":
+        _cast_gguf(target, out_path, vf32, vref, meta, args, op, vraw=vraw, vqtype=vqtype, strict_target=strict_target)
+        return
+    # safetensors target
+    header, tensors = read_safetensors(target)
+    t0s = time.time()
+    tname, data, tdtype, tshape = _cast_st_prepare(target, tensors, vf32, vref, meta, args,
+                                                  vraw=vraw, vqtype=vqtype, strict_target=strict_target)
+    _step(f"Replacing {tname} ({tdtype} {tshape})…")
+    rewrite_safetensors_tensor(target, out_path, tname, data, tdtype, tshape)
+    file_size = os.path.getsize(out_path)
+    try:
+        _note(f"Kept {len(data)/1e6:.1f} MB → {tdtype} @ {(len(data)/1e6)/max(time.time()-t0s,1e-6):.0f} MB/s")
+    except Exception:
+        pass
+    log_operation({"op": op, "target": target, "format": "safetensors", "tensor": tname,
+                   "dtype": tdtype, "shape": list(tshape), "output": out_path, "status": "ok"})
+    _ok(f"Done → {out_path}")
+    _say(f"  Tensor replaced at {tdtype} ({file_size/1e6:.1f} MB).")
+
+
+def _is_head_name(name):
+    if not name:
+        return False
+    try:
+        if name in OUTPUT_ALIASES or name in ("token_embd.weight",):
+            return True
+        for a in OUTPUT_ALIASES:
+            if name.endswith(a):
+                return True
+    except Exception:
+        pass
+    return False
+
+
+def _parse_quant_override(s):
+    # Returns normalized key: keep|target or Q-type name upper (e.g. Q4_0). Trivial: accept all GGML quants.
+    if s is None:
+        return "keep"
+    k = str(s).strip().lower().replace("-", "_")
+    if k in ("keep", "target"):
+        return k
+    # Aliases for float family.
+    if k in ("fp32",):
+        k = "f32"
+    if k in ("fp16",):
+        k = "f16"
+    # Try any GGMLQuantizationType name.
+    try:
+        from gguf.constants import GGMLQuantizationType as _Qp
+        # Case-insensitive match against all Q names.
+        for _q in _Qp:
+            if _q.name.lower() == k:
+                return k
+    except Exception:
+        pass
+    # Fallback known list (when gguf import fails).
+    _known = {"f32", "f16", "bf16", "q8_0", "q8_1", "q8_k", "q1_0", "q4_0", "q4_1", "q5_0", "q5_1",
+              "q2_k", "q3_k", "q4_k", "q5_k", "q6_k", "iq1_s", "iq1_m", "iq2_xxs", "iq2_xs", "iq2_s",
+              "iq3_xxs", "iq3_s", "iq4_nl", "iq4_xs", "tq1_0", "tq2_0", "mxfp4", "nvfp4"}
+    if k in _known:
+        return k
+    return None
+
+
+def _quant_from_key(key):
+    # key normalized via _parse_quant_override (lower). Returns Q type or None for keep/target.
+    if key in ("keep", "target", None):
+        return None
+    try:
+        from gguf.constants import GGMLQuantizationType as _Qq
+        for _q in _Qq:
+            if _q.name.lower() == key:
+                return _q
+        # Upper direct (e.g. Q4_0).
+        return _Qq[key.upper()]
+    except Exception:
+        return None
+
+
+def _qerr(e):
+    """Readable lib error: gguf often raises bare NotImplementedError ('')."""
+    s = str(e).strip()
+    return f"{type(e).__name__}: {s}" if s else type(e).__name__
+
+
+_NEAREST_CACHE = {}
+
+
+def _nearest_encodable(target_q):
+    """Nearest gguf-encodable quant to target_q by bits/param (ties → larger =
+    quality-preserving). The lib decodes everything but encodes only a subset
+    (no K/IQ quants); this keeps fused tensors near the original size instead
+    of ballooning to F16. Support probed once per process (version-proof)."""
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.constants import GGML_QUANT_SIZES as S
+    from gguf.quants import quantize
+    key = getattr(target_q, "name", str(target_q))
+    if key in _NEAREST_CACHE:
+        return _NEAREST_CACHE[key]
+    tbpp = S[target_q][1] * 8 / S[target_q][0]
+    probe = (np.arange(64 * 64, dtype=np.float32).reshape(64, 64) - 2048) / 64
+    scored = []
+    for name in ("Q8_0", "Q5_1", "Q5_0", "Q4_1", "Q4_0", "MXFP4", "F16"):
+        cand = getattr(Q, name, None)
+        if cand is None or cand == target_q:
+            continue
+        try:
+            quantize(probe, cand)
+        except Exception:
+            continue
+        cbpp = S[cand][1] * 8 / S[cand][0]
+        scored.append((abs(cbpp - tbpp), -cbpp, cand))
+    best = min(scored)[2] if scored else None
+    _NEAREST_CACHE[key] = best
+    return best
+
+def _quantize_to_Q(fused, req_q):
+    # Quantize F32 fused array to any Q (F32/F16/BF16 via astype, else gguf quantize).
+    # Returns (q_head, out_qtype). Raises on unsupported (e.g. Q1_0/Q8_1/Q8_K NotImplemented).
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import quantize
+    if req_q in (Q.F32,):
+        return fused.astype(np.float32), Q.F32
+    if req_q in (Q.F16,):
+        return fused.astype(np.float16), Q.F16
+    try:
+        _b = getattr(Q, "BF16", None)
+    except Exception:
+        _b = None
+    if _b is not None and req_q == _b:
+        _u32 = fused.astype(np.float32).view(np.uint32)
+        return (((_u32 + 0x7FFF + ((_u32 >> 16) & 1)) >> 16).astype(np.uint16), _b)
+    # All other GGML quants (Q4_0/Q4_K/Q6_K/IQ*/TQ*/MXFP4/...) via single quantize call (trivial).
+    return quantize(fused, req_q), req_q
+
+
+def _fuse_delta(target_tensor, delta_f32, strict=False):
+    """Dequant the target head once to F32 and fuse the delta (head + delta).
+    Single seam for the three dequant→fuse sites in _gguf_fuse_one.
+    strict (safetensors delta path only): fail clean on shape mismatch, exactly as before."""
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    if target_tensor.tensor_type in (Q.F32, Q.F16):
+        try:
+            head_f32 = target_tensor.data.astype(np.float32)
+        except Exception:
+            head_f32 = np.asarray(target_tensor.data, dtype=np.float32)
+    else:
+        from gguf.quants import dequantize as _deq
+        head_f32 = _deq(target_tensor.data, target_tensor.tensor_type)
+    if strict and head_f32.shape != delta_f32.shape:
+        sys.stdout.write("\n")
+        _fail(f"  ✗ Style shape {delta_f32.shape} doesn't match model head {head_f32.shape}.")
+    return np.ascontiguousarray(head_f32 + delta_f32)
+
+
+def _gguf_fuse_one(target, target_tensor, tname, logical, vf32, vref, meta, args, op, vraw=None, vqtype=None):
+    """Fuse one voice tensor into its target GGUF tensor form. Returns (q_head, out_qtype)."""
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import quantize
+    # Philosophy: preserve quality, avoid dequant->quant cycles.
+    # - GGUF quant voice (vraw) is kept at its obtained quant (never upscale Q2->Q6, no inventing data).
+    # - Safetensors high-fidelity lm_head (voice) is quantized once to Q8_0.
+    # - Generic tensors keep target quant (F32 norms stay F32, never forced Q8_0).
+    # - All GGML quants supported (trivial passthrough + quantize where implemented).
+    _quant_override = _parse_quant_override(getattr(args, "quant", None) or "keep")
+    if _quant_override is None:
+        _fail(f"  ✗ Invalid --quant '{getattr(args, 'quant', None)}'. Use keep|target|<any quant like q8_0,q4_0,q4_k,q6_k,iq4_nl,f16,f32,bf16>.")
+    _is_head = _is_head_name(vref.name) or _is_head_name(tname)
+    _is_delta = (meta or {}).get("type") == "delta"
+    # Show quant/target by default for advanced tensor commands (and verbose for voice)
+    try:
+        _tq = target_tensor.tensor_type.name
+    except Exception:
+        _tq = "?"
+    try:
+        _vq = vqtype if vraw is not None else vref.dtype
+    except Exception:
+        _vq = "?"
+    if ctx.VERBOSE:
+        _note(f"Voice '{vref.name}' is {_vq} {tuple(vref.shape)} → target '{tname}' is {_tq} {logical}")
+    if vraw is not None:
+        # GGUF quant voice: keep obtained quant (no upscale, no extra cycle).
+        try:
+            _vqtype = Q[vqtype]
+        except Exception:
+            _fail(f"  ✗ Unknown voice quant '{vqtype}'.")
+        if tuple(vref.shape) != logical:
+            _fail(f"  ✗ Voice shape {vref.shape} doesn't fit target tensor {tname} {logical}.")
+        if _quant_override in ("keep",):
+            # Transplant quant type as-is (may differ from target type — intentional, preserves quality).
+            if _vqtype.name != target_tensor.tensor_type.name and ctx.VERBOSE:
+                _note(f"Keeping voice quant {_vqtype.name} (target was {target_tensor.tensor_type.name}, not upscaling).")
+            _step(f"Casting onto {os.path.basename(target)} ({_vqtype.name}, kept)…")
+            from gguf.quants import quant_shape_to_byte_shape as _q2b_keep
+            _keep_shape = _q2b_keep(tuple(int(x) for x in vref.shape), _vqtype)
+            _need = 1
+            for _d in _keep_shape:
+                _need *= _d
+            _raw = np.frombuffer(vraw, dtype=np.uint8)
+            if _raw.size < _need:
+                _fail(f"  ✗ Short voice data for transplant ({_raw.size}/{_need} bytes).")
+            q_head, out_qtype = _raw[:_need].reshape(_keep_shape), _vqtype
+        elif _quant_override == "target":
+            # Explicit: dequant once then quant to target (extra cycle, warn).
+            _warn(f"Re-quanting voice {_vqtype.name} → target {target_tensor.tensor_type.name} (extra dequant→quant cycle).")
+            from gguf.quants import dequantize as _deq2
+            from gguf.quants import quant_shape_to_byte_shape as _q2b
+            # vref.shape is logical already checked
+            _rshape = tuple(vref.shape)
+            try:
+                _f32v = _deq2(np.frombuffer(vraw, dtype=np.uint8).reshape(_q2b(_rshape, _vqtype)), _vqtype)
+            except Exception as e:
+                _fail(f"  ✗ Could not dequant voice for --quant target: {e}")
+            if _is_delta:
+                _f32v = _fuse_delta(target_tensor, _f32v)
+            t_quant0 = time.time()
+            _tq2 = target_tensor.tensor_type
+            if _tq2 in (Q.F32,):
+                q_head, out_qtype = _f32v.astype(np.float32), Q.F32
+            elif _tq2 in (Q.F16,):
+                q_head, out_qtype = _f32v.astype(np.float16), Q.F16
+            else:
+                try:
+                    _bf = getattr(Q, "BF16", None)
+                except Exception:
+                    _bf = None
+                if _bf is not None and _tq2 == _bf:
+                    # BF16 target: gguf lib has no BF16 encoder here; keep F32 to avoid loss
+                    q_head, out_qtype = _f32v.astype(np.float32), Q.F32
+                    _warn("  BF16 target: keeping F32 to avoid loss (use --quant f16/bf16 explicitly if needed).")
+                else:
+                    try:
+                        q_head, out_qtype = quantize(_f32v, _tq2), _tq2
+                    except Exception as e:
+                        _fail(f"  ✗ Could not quant to target {_tq2.name}: {e}")
+            _note(f"Re-quantized {_f32v.nbytes/1e6:.1f} MB → {_tq2.name} @ {(_f32v.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+        else:
+            # Explicit q8_0/f16/f32/bf16 for quant voice: dequant once then quant.
+            from gguf.quants import dequantize as _deq2
+            from gguf.quants import quant_shape_to_byte_shape as _q2b
+            _rshape = tuple(vref.shape)
+            try:
+                _f32v = _deq2(np.frombuffer(vraw, dtype=np.uint8).reshape(_q2b(_rshape, _vqtype)), _vqtype)
+            except Exception as e:
+                _fail(f"  ✗ Could not dequant voice for --quant {_quant_override}: {e}")
+            if _is_delta:
+                _f32v = _fuse_delta(target_tensor, _f32v)
+            _qn = _quant_from_key(_quant_override)
+            if _qn is None:
+                _fail(f"  ✗ Invalid --quant '{_quant_override}'.")
+            t_quant0 = time.time()
+            try:
+                q_head, out_qtype = _quantize_to_Q(_f32v, _qn)
+            except NotImplementedError as e:
+                _fail(f"  ✗ Quant {getattr(_qn, 'name', _quant_override)} not implemented by gguf lib ({e}). Keeping original is recommended.")
+            except Exception as e:
+                _fail(f"  ✗ Could not quant to {_quant_override}: {e}")
+            _note(f"Quantized {_f32v.nbytes/1e6:.1f} MB → {out_qtype.name} @ {(_f32v.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+    else:
+        oriented = _orient(vf32, vref.shape, logical)
+        if oriented is None:
+            _fail(f"  ✗ Voice shape {vref.shape} doesn't fit target tensor {tname} {logical}.")
+        t_fuse0 = time.time()
+        # Decide out quant: Q8_0 once only for safetensors high-fidelity heads; else keep target.
+        # vref.dtype here is F32/F16/BF16 (high-fidelity, since vraw is None).
+        _target_q = target_tensor.tensor_type
+        # Explicit override wins (any quant trivially supported via _quantize_to_Q).
+        _req = None
+        if _quant_override != "keep":
+            if _quant_override == "target":
+                _req = _target_q
+            else:
+                _req = _quant_from_key(_quant_override)
+                if _req is None:
+                    _fail(f"  ✗ Invalid --quant '{_quant_override}'.")
+        t_fuse0 = time.time()
+        if _is_delta:
+            # Fuse first (F32 math preserves quality), decide quant after.
+            fused = _fuse_delta(target_tensor, oriented, strict=True)
+            if _req is not None:
+                # Explicit --quant for delta (all quants trivial via helper).
+                _step(f"Fusing style into {tname} (delta + head → {_req.name})…")
+                t_quant0 = time.time()
+                try:
+                    q_head, out_qtype = _quantize_to_Q(fused, _req)
+                except NotImplementedError as e:
+                    _fail(f"  ✗ Quant {_req.name} not implemented by gguf lib ({e}). Keeping original is recommended.")
+                except Exception as e:
+                    _fail(f"  ✗ Could not quant delta to {_req.name}: {e}")
+                _note(f"Quantized {fused.nbytes/1e6:.1f} MB → {_req.name} @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+            elif _is_head:
+                # Head delta from high-fidelity: Q8_0 once (old behavior, with %32 fallback).
+                if fused.shape[-1] % 32 != 0:
+                    _warn(f"Head last dim {fused.shape[-1]} not ×32 — Q8_0 needs %32, keeping F16 (larger, compatible).")
+                    _step(f"Fusing style into {tname} (delta + head → F16 fallback)…")
+                    q_head, out_qtype = fused.astype(np.float16), Q.F16
+                else:
+                    _step(f"Fusing style into {tname} (delta + head → Q8_0)…")
+                    t_quant0 = time.time()
+                    try:
+                        q_head, out_qtype = quantize(fused, Q.Q8_0), Q.Q8_0
+                    except Exception as e:
+                        _fail(f"  ✗ Could not quant delta to Q8_0: {e}")
+                    _note(f"Quantized {fused.nbytes/1e6:.1f} MB → Q8_0 @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+            else:
+                # Generic delta: keep target quant (never force Q8_0). Never upscale implicitly.
+                _step(f"Fusing style into {tname} (delta + head → {_target_q.name}, kept)…")
+                t_quant0 = time.time()
+                if _target_q in (Q.F32,):
+                    q_head, out_qtype = fused.astype(np.float32), Q.F32
+                elif _target_q in (Q.F16,):
+                    q_head, out_qtype = fused.astype(np.float16), Q.F16
+                else:
+                    try:
+                        _b = getattr(Q, "BF16", None)
+                    except Exception:
+                        _b = None
+                    if _b is not None and _target_q == _b:
+                        q_head, out_qtype = fused.astype(np.float32), Q.F32
+                        _warn("  BF16 target: keeping F32 to avoid loss (use --quant bf16 explicitly if needed).")
+                        out_qtype = Q.F32
+                    else:
+                        try:
+                            q_head, out_qtype = quantize(fused, _target_q), _target_q
+                        except Exception as e:
+                            _near = _nearest_encodable(_target_q)
+                            if _near is not None:
+                                _warn(f"  {_target_q.name} not encodable ({_qerr(e)}); keeping {_near.name} (nearest size) instead of F16.")
+                                q_head, out_qtype = _quantize_to_Q(fused, _near)
+                            else:
+                                _warn(f"  Could not quant to {_target_q.name} ({_qerr(e)}), keeping F16.")
+                                q_head, out_qtype = fused.astype(np.float16), Q.F16
+                try:
+                    _note(f"Fused {fused.nbytes/1e6:.1f} MB → {out_qtype.name} @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+                except Exception:
+                    pass
+        else:
+            # Not delta: voice replace (all quants trivial).
+            if _req is not None:
+                _step(f"Casting onto {os.path.basename(target)} ({_req.name})…")
+                fused = oriented
+                t_quant0 = time.time()
+                try:
+                    q_head, out_qtype = _quantize_to_Q(fused, _req)
+                except NotImplementedError as e:
+                    _fail(f"  ✗ Quant {_req.name} not implemented by gguf lib ({e}).")
+                except Exception as e:
+                    _fail(f"  ✗ Could not quant to {_req.name}: {e}")
+                _note(f"Quantized {fused.nbytes/1e6:.1f} MB → {_req.name} @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+            elif _is_head:
+                # lm_head high-fidelity: quant once to Q8_0 (preserve quality, Q4 saves little).
+                if oriented.shape[-1] % 32 != 0:
+                    _warn(f"Head last dim {oriented.shape[-1]} not ×32 — Q8_0 needs %32, keeping F16 (larger, compatible).")
+                    _step(f"Casting onto {os.path.basename(target)} (F16 fallback)…")
+                    fused = oriented
+                    q_head, out_qtype = fused.astype(np.float16), Q.F16
+                else:
+                    _step(f"Casting onto {os.path.basename(target)} (Q8_0)…")
+                    fused = oriented
+                    t_quant0 = time.time()
+                    try:
+                        q_head, out_qtype = quantize(fused, Q.Q8_0), Q.Q8_0
+                    except Exception as e:
+                        sys.stdout.write("\n")
+                        if ctx.VERBOSE:
+                            _say(f"  Details: {e}")
+                        _fail("  ✗ Could not prepare the voiced model. Try again.")
+                    _note(f"Quantized {fused.nbytes/1e6:.1f} MB → Q8_0 @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+            else:
+                # Generic tensor: keep target quant (fix crash: F32 norms stay F32, never forced Q8_0).
+                _tq = _target_q
+                try:
+                    _tqn = _tq.name
+                except Exception:
+                    _tqn = str(_tq)
+                try:
+                    _vqn = vref.dtype
+                except Exception:
+                    _vqn = "?"
+                # Mismatch prompt only for safetensors non-head high-fidelity differing from target.
+                _need_prompt = (_vqn.upper() in ("F32", "F16", "BF16", "FP32", "FP16") and _tqn.upper() != _vqn.upper())
+                _custom_done = False
+                if _need_prompt and _quant_override == "keep" and not _noninteractive(args):
+                    try:
+                        _say(f"  Target '{tname}' is {_tqn}, fetched is {_vqn}.")
+                        _ans = input(f"  Press enter to quantize to {_tqn} or enter custom quant (any like Q8_0/Q4_0/Q6_K/F16/F32/BF16): ").strip()
+                    except (EOFError, KeyboardInterrupt):
+                        _say("  ⚠ Cancelled.")
+                        sys.exit(0)
+                    _ans_n = _ans.strip().upper().replace("-", "_")
+                    if _ans.strip() == "" or _ans_n == _tqn.upper():
+                        pass
+                    else:
+                        _ck = _parse_quant_override(_ans)
+                        _cq = _quant_from_key(_ck) if _ck not in (None, "keep", "target") else None
+                        if _ck is None or (_cq is None and _ck not in ("keep", "target")):
+                            _warn(f"  Unknown quant '{_ans}', using target {_tqn}.")
+                        elif _ck == "target" or _ans_n == _tqn.upper():
+                            pass
+                        else:
+                            _warn(f"Forcing {_ans} for generic tensor (extra quant cycle).")
+                            fused = oriented
+                            t_quant0 = time.time()
+                            try:
+                                q_head, out_qtype = _quantize_to_Q(fused, _cq)
+                            except NotImplementedError as e:
+                                _fail(f"  ✗ Quant {_cq.name} not implemented ({e}).")
+                            except Exception as e:
+                                _fail(f"  ✗ Could not quant to {_cq.name}: {e}")
+                            _note(f"Quantized {fused.nbytes/1e6:.1f} MB → {_cq.name} @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+                            _note(f"Fusing done in {time.time()-t_fuse0:.1f}s")
+                            _custom_done = True
+                # keep-target path (default, silent when match, Enter=target when mismatch)
+                if not _custom_done:
+                    _step(f"Casting '{vref.name}' ({_vqn}) onto '{tname}' ({_tqn}, kept)…")
+                    fused = oriented
+                    t_quant0 = time.time()
+                    if _tq in (Q.F32,):
+                        q_head, out_qtype = fused.astype(np.float32), Q.F32
+                    elif _tq in (Q.F16,):
+                        q_head, out_qtype = fused.astype(np.float16), Q.F16
+                    else:
+                        try:
+                            _b = getattr(Q, "BF16", None)
+                        except Exception:
+                            _b = None
+                        if _b is not None and _tq == _b:
+                            q_head, out_qtype = fused.astype(np.float32), Q.F32
+                            _warn("  BF16 target: keeping F32 to avoid loss (use --quant bf16 explicitly if needed).")
+                            out_qtype = Q.F32
+                        else:
+                            try:
+                                q_head, out_qtype = quantize(fused, _tq), _tq
+                            except Exception as e:
+                                _near = _nearest_encodable(_tq)
+                                if _near is not None:
+                                    _warn(f"  {_tqn} not encodable ({_qerr(e)}); keeping {_near.name} (nearest size) instead of F16.")
+                                    q_head, out_qtype = _quantize_to_Q(fused, _near)
+                                else:
+                                    _warn(f"  Could not quant to {_tqn} ({_qerr(e)}), keeping F16.")
+                                    q_head, out_qtype = fused.astype(np.float16), Q.F16
+                    try:
+                        _note(f"Kept {fused.nbytes/1e6:.1f} MB → {out_qtype.name} @ {(fused.nbytes/1e6)/max(time.time()-t_quant0,1e-6):.0f} MB/s")
+                    except Exception:
+                        pass
+        try:
+            t_fuse0
+        except Exception:
+            t_fuse0 = time.time()
+        _note(f"Fusing done in {time.time()-t_fuse0:.1f}s")
+    return q_head, out_qtype
+
+
+def _gguf_write_repl(target, reader, arch, repl, out_path, args, op, detail=None, _extra_names=()):
+    """Single-pass GGUF write. repl maps tensor name -> (array, ggml_type).
+    detail (single-tensor callers): (tname, logical, vref, vraw, vqtype, meta) for rich messages."""
+    from gguf import GGUFWriter
+    from gguf.gguf_writer import GGUFValue
+    from gguf.constants import GGMLQuantizationType as Q
+    if not arch:
+        _warn("  Target architecture unknown — labeling output 'llama' (GGUF requires an arch).")
+    writer = GGUFWriter(out_path, arch or "llama", use_temp_file=True)
+    for field in reader.fields.values():
+        if field.name in ("general.architecture",) or field.name.startswith("GGUF."):
+            continue
+        try:
+            val = field.contents()
+        except Exception:
+            continue
+        vtype = field.types[0] if field.types else None
+        if vtype is None:
+            continue
+        subtype = field.types[-1] if len(field.types) > 1 else None
+        try:
+            writer.kv_data[0][field.name] = GGUFValue(value=val, type=vtype, sub_type=subtype)
+        except Exception:
+            try:
+                writer.add_key_value(field.name, val, vtype, subtype)
+            except Exception:
+                if ctx.VERBOSE:
+                    _warn(f"Could not copy field {field.name}")
+
+    for t in reader.tensors:
+        if t.name in repl:
+            _qh, _qt = repl[t.name]
+            writer.add_tensor(t.name, _qh, raw_dtype=_qt)
+        elif t.tensor_type in (Q.F32, Q.F16):
+            writer.add_tensor(t.name, t.data)
+        else:
+            writer.add_tensor(t.name, t.data, raw_dtype=t.tensor_type)
+    for name in _extra_names:
+        if name in repl and name not in [t.name for t in reader.tensors]:
+            _qh, _qt = repl[name]
+            writer.add_tensor(name, _qh, raw_dtype=_qt)
+
+    # writing GGUF is the long wait (often 5-30s for 26GB) — show bar with speed, internet or local
+    _step(f"Writing {out_path} …")
+    # estimate total bytes for progress — use data.nbytes
+    try:
+        total_write = 8192
+        for t in reader.tensors:
+            if t.name in repl:
+                continue
+            try:
+                total_write += int(t.data.nbytes)
+            except Exception as e:
+                if ctx.VERBOSE:
+                    _warn(f"progress estimate for {t.name} failed: {e}")
+        try:
+            for _qh, _qt in repl.values():
+                total_write += int(_qh.nbytes)
+        except Exception:
+            try:
+                for _qh, _qt in repl.values():
+                    total_write += int(_qh.size * _qh.itemsize)
+            except Exception:
+                pass
+        if ctx.VERBOSE:
+            _note(f"Estimated write {total_write/1e6:.1f} MB ({len(repl)} replaced + {len([t for t in reader.tensors if t.name not in repl])} copied)")
+    except Exception as e:
+        if ctx.VERBOSE:
+            _warn(f"progress estimate failed: {e}")
+        total_write = 0
+    # ensure total_write is at least header + heads for small models, never 0 for progress
+    if total_write < 1000:
+        try:
+            total_write = 8192
+            for _qh, _qt in repl.values():
+                try:
+                    total_write += int(_qh.nbytes)
+                except Exception:
+                    pass
+            for t in reader.tensors:
+                if t.name not in repl:
+                    try:
+                        total_write += int(t.data.nbytes)
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+        if total_write < 1000:
+            total_write = 0
+    t_write0 = time.time()
+    last_w = [0.0]
+    # progress poll for GGUF write (local disk, but user is waiting)
+    import threading
+    _stop_poll = [False]
+    def _poll_gguf():
+        # poll output file (or temp file) size
+        target_path = getattr(writer, 'fname', out_path)
+        # GGUFWriter with use_temp_file=True writes to temp file with suffix
+        # fallback to out_path
+        poll_path = target_path if os.path.exists(target_path) else out_path
+        # try to find temp file if not yet at final path
+        while not _stop_poll[0]:
+            try:
+                cur = 0
+                if os.path.exists(poll_path):
+                    cur = os.path.getsize(poll_path)
+                else:
+                    # try temp file pattern
+                    import glob
+                    tmps = glob.glob(str(out_path) + "*")
+                    for p in tmps:
+                        if os.path.isfile(p):
+                            try:
+                                cur = max(cur, os.path.getsize(p))
+                            except Exception:
+                                pass
+                elapsed = time.time() - t_write0 or 1e-6
+                mbps = cur / elapsed / 1e6
+                pct = (cur / total_write * 100) if total_write else 0
+                if pct > 100:
+                    pct = 100
+                if total_write:
+                    msg = f"  → writing {pct:3.0f}% · {cur/1e6:.1f}/{total_write/1e6:.1f} MB · {mbps:.0f} MB/s  "
+                else:
+                    msg = f"  → writing {cur/1e6:.1f} MB · {mbps:.0f} MB/s  "
+                sys.stdout.write(_transform(msg) + ("\n" if _progress_pref() else "\r"))
+                sys.stdout.flush()
+            except Exception:
+                pass
+            time.sleep(0.25)
+    _thr = threading.Thread(target=_poll_gguf, daemon=True)
+    _thr.start()
+    try:
+        writer.write_header_to_file()
+        writer.write_kv_data_to_file()
+        writer.write_tensors_to_file()
+        writer.close()
+    except Exception as e:
+        _stop_poll[0] = True
+        try:
+            _thr.join(timeout=0.5)
+        except Exception:
+            pass
+        sys.stdout.write("\n")
+        if ctx.VERBOSE:
+            _say(f"  Details: {e}")
+        _fail(f"  ✗ Could not save the voiced model to {out_path}.")
+    _stop_poll[0] = True
+    try:
+        _thr.join(timeout=0.5)
+    except Exception:
+        pass
+    sys.stdout.write("\n")
+    elapsed_w = time.time() - t_write0 or 1e-6
+    try:
+        final_sz = os.path.getsize(out_path)
+        _note(f"Wrote {final_sz/1e6:.1f} MB @ {final_sz/elapsed_w/1e6:.0f} MB/s")
+    except Exception:
+        pass
+
+    file_size = os.path.getsize(out_path)
+    if detail is None:
+        summed = [(n, _qt.name if hasattr(_qt, "name") else str(_qt)) for n, (_qh, _qt) in repl.items()]
+        log_operation({"op": op, "target": target, "format": "gguf", "tensors": summed,
+                       "output": out_path, "status": "ok"})
+        _ok(f"Done → {out_path}")
+        for n, _qt in summed:
+            _say(f"  Cast '{n}' → {_qt} ({file_size/1e6:.1f} MB total).")
+        _say(f"  Load it: llama serve -m {out_path}")
+        return
+    tname, logical, vref, vraw, vqtype, meta = detail
+    _qh0, out_qtype = repl[tname]
+    log_operation({"op": op, "target": target, "format": "gguf", "tensor": tname,
+                   "dtype": out_qtype.name, "shape": list(logical), "output": out_path, "status": "ok"})
+    _ok(f"Done → {out_path}")
+    is_fallback = 'fallback_to_f16' in locals() and locals().get('fallback_to_f16')
+    _is_head_msg = _is_head_name(tname) or _is_head_name(getattr(vref, "name", None))
+    _label = "Head" if _is_head_msg else "Tensor"
+    if (meta or {}).get("type") == "delta" and is_fallback:
+        _say(f"  Style fused and head kept as F16 (Q8_0 needs %32, fallback) ({file_size/1e6:.1f} MB).")
+    elif (meta or {}).get("type") == "delta":
+        # Delta head keeps Q8_0 for heads, keeps target for generic.
+        if _is_head_msg and out_qtype == Q.Q8_0:
+            _say(f"  Style fused and head quantized to Q8_0 ({file_size/1e6:.1f} MB).")
+        else:
+            _say(f"  Style fused into '{tname}' → {out_qtype.name}, kept ({file_size/1e6:.1f} MB).")
+    elif is_fallback:
+        _say(f"  Head kept as F16 (Q8_0 needs last dim %32, fallback) ({file_size/1e6:.1f} MB).")
+    elif out_qtype == Q.Q8_0 and _is_head_msg:
+        _qo = _parse_quant_override(getattr(args, "quant", None) or "keep")
+        _kept_q8 = (vraw is not None and isinstance(vqtype, str) and vqtype == Q.Q8_0.name and _qo in ("keep",))
+        if _kept_q8:
+            _say(f"  Head kept as Q8_0 (from {vqtype}, {file_size/1e6:.1f} MB).")
+        else:
+            _say(f"  Head quantized to Q8_0 ({file_size/1e6:.1f} MB).")
+    else:
+        _from = vqtype if vraw is not None else getattr(vref, "dtype", "?")
+        _say(f"  {_label} '{tname}' kept as {out_qtype.name} (from {_from}, {file_size/1e6:.1f} MB).")
+    _say(f"  Load it: llama serve -m {out_path}")
+
+
+def _read_gguf_arch(reader):
+    """Single arch-reader for GGUF targets. Returns the general.architecture string or None."""
+    import numpy as np
+    for field in reader.fields.values():
+        if field.name == "general.architecture":
+            try:
+                raw = field.parts[field.data[0]]
+                return raw.tobytes().decode() if isinstance(raw, np.ndarray) else str(raw)
+            except Exception:
+                return None
+    return None
+
+
+def _confirm_arch_mismatch(varch, arch, args):
+    """Single mismatch warn (+ confirm) shared by single and pack GGUF casts."""
+    if varch and arch and varch.lower() != arch.lower():
+        _warn(f"This voice was trained for a {varch} model, but the target is {arch}. It may not sound right.")
+        if not _confirm("  Continue anyway? [y/N]: ", args):
+            _note("Cancelled.")
+            sys.exit(0)
+
+
+def _cast_gguf_speak(target, reader, arch, out_path, vf32, vref, meta, args, op, vraw=None, vqtype=None):
+    """--speak: voice onto output.weight, invented if absent. GGUF only."""
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import quantize, quant_shape_to_byte_shape
+    if (meta or {}).get("type") == "delta":
+        _fail("  ✗ --speak cannot place a delta voice (differences are not weights).")
+    names = [t.name for t in reader.tensors]
+    ot = next((t for t in reader.tensors if t.name == "output.weight"), None)
+    et = next((t for t in reader.tensors if t.name == "token_embd.weight"), None)
+    if ot is not None:
+        olog = tuple(reversed(tuple(int(x) for x in ot.shape)))
+        invented = False
+    elif et is not None:
+        olog = tuple(reversed(tuple(int(x) for x in et.shape)))
+        invented = True
+    else:
+        _fail("  ✗ Target has no output.weight or token_embd.weight to mirror geometry from.")
+    varch = (meta or {}).get("architecture")
+    _confirm_arch_mismatch(varch, arch, args)
+    tname = "output.weight"
+    if vraw is not None:
+        _vqtype = Q[vqtype]
+        if tuple(vref.shape) != olog:
+            _fail(f"  ✗ Voice shape {vref.shape} doesn't fit {tname} {olog}.")
+        _qo = _parse_quant_override(getattr(args, "quant", None) or "keep")
+        if _qo not in ("keep",):
+            fitted = _gguf_raw_to_f32(vraw, _vqtype, tuple(int(x) for x in vref.shape))
+            q_head, out_qtype = _quantize_to_Q(np.ascontiguousarray(fitted), Q[_qo])
+        else:
+            _need = 1
+            for _d in quant_shape_to_byte_shape(tuple(int(x) for x in vref.shape), _vqtype):
+                _need *= _d
+            _raw = np.frombuffer(vraw, dtype=np.uint8)
+            if _raw.size < _need:
+                _fail(f"  ✗ Voice data too short for {vqtype} {tuple(vref.shape)}.")
+            q_head = np.ascontiguousarray(_raw[:_need].reshape(
+                quant_shape_to_byte_shape(tuple(int(x) for x in vref.shape), _vqtype)))
+            out_qtype = _vqtype
+    else:
+        fitted = _orient(vf32, vref.shape, olog)
+        if fitted is None:
+            _fail(f"  ✗ Voice shape {vref.shape} doesn't fit {tname} {olog}.")
+        fitted = np.ascontiguousarray(fitted)
+        _qo = _parse_quant_override(getattr(args, "quant", None) or "keep")
+        if _qo is None:
+            _fail(f"  ✗ Invalid --quant '{getattr(args, 'quant', None)}'.")
+        if _qo not in ("keep",):
+            q_head, out_qtype = _quantize_to_Q(fitted, Q[_qo])
+        elif fitted.shape[-1] % 32 == 0:
+            q_head, out_qtype = quantize(fitted, Q.Q8_0), Q.Q8_0
+        else:
+            _note("  last dim not x32 - added output kept F16")
+            q_head, out_qtype = fitted.astype(np.float16), Q.F16
+    if invented:
+        _note("speak: voice -> invented output.weight (file untied)")
+    else:
+        _note("speak: voice -> output.weight")
+    _gguf_write_repl(target, reader, arch, {tname: (q_head, out_qtype)}, out_path, args, op,
+                      detail=(tname, olog, vref, vraw, vqtype, meta),
+                      _extra_names=(tname,) if invented else ())
+
+def _cast_gguf(target, out_path, vf32, vref, meta, args, op, vraw=None, vqtype=None, strict_target=False):
+    import numpy as np
+    from gguf import GGUFReader
+
+    reader = GGUFReader(target)
+    arch = _read_gguf_arch(reader)
+
+    if getattr(args, "speak", False):
+        _cast_gguf_speak(target, reader, arch, out_path, vf32, vref, meta, args, op, vraw=vraw, vqtype=vqtype)
+        return
+    target_tensor = None
+    if vref.name:
+        for t in reader.tensors:
+            if t.name == vref.name:
+                target_tensor = t
+                break
+    if target_tensor is None and strict_target:
+        _fail(f"  ✗ Tensor '{vref.name}' not found in target {target}. Voicepack requires exact match (not mapping to another tensor).")
+    if target_tensor is None:
+        for preferred in ("output.weight", "token_embd.weight"):
+            for t in reader.tensors:
+                if t.name == preferred:
+                    target_tensor = t
+                    break
+            if target_tensor is not None:
+                break
+    if target_tensor is None:
+        _fail("  ✗ Target has no output.weight or token_embd.weight to receive the voice.")
+
+    tname = target_tensor.name
+    logical = tuple(reversed(tuple(int(x) for x in target_tensor.shape)))
+
+    # arch mismatch warning
+    varch = (meta or {}).get("architecture")
+    _confirm_arch_mismatch(varch, arch, args)
+
+    q_head, out_qtype = _gguf_fuse_one(target, target_tensor, tname, logical, vf32, vref, meta, args, op, vraw=vraw, vqtype=vqtype)
+    _gguf_write_repl(target, reader, arch, {tname: (q_head, out_qtype)}, out_path, args, op,
+                      detail=(tname, logical, vref, vraw, vqtype, meta))
+
+
+# GGUF (llama.cpp) <-> safetensors (HF) tensor-name aliases, matched by
+# (block index, role). Exact name match always wins; aliases only fire on a
+# miss, and only when exactly one candidate matches. Anything else fails loud
+# at the call site — never a silent mapping to another tensor.
+_ROLE_ALIASES = (
+    ("embed_tokens.weight", "token_embd.weight"),
+    ("word_embeddings.weight", "token_embd.weight"),
+    ("wte.weight", "token_embd.weight"),
+    ("output_layer.weight", "output.weight"),
+    ("lm_head.weight", "output.weight"),
+    ("final_layernorm.weight", "output_norm.weight"),
+    ("self_attention.dense.weight", "attn_output.weight"),
+    ("mlp.dense_4h_to_h.weight", "ffn_down.weight"),
+    ("model.norm.weight", "output_norm.weight"),
+    ("ln_f.weight", "output_norm.weight"),
+    ("input_layernorm.weight", "attn_norm.weight"),
+    ("self_attn.q_proj.weight", "attn_q.weight"),
+    ("self_attn.k_proj.weight", "attn_k.weight"),
+    ("self_attn.v_proj.weight", "attn_v.weight"),
+    ("self_attn.o_proj.weight", "attn_o.weight"),
+    ("self_attn.o_proj.weight", "attn_output.weight"),
+    ("post_attention_layernorm.weight", "post_attention_norm.weight"),
+    ("mlp.down_proj.weight", "ffn_down.weight"),
+    ("experts.down_proj", "ffn_down_exps.weight"),
+    ("mlp.up_proj.weight", "ffn_up.weight"),
+)
+
+
+def _block_index(name):
+    import re
+    m = re.search(r"(?<![A-Za-z0-9_])(?:layers|layer|blk|blks|blocks|h)\.(\d+)\b", name)
+    if m:
+        return int(m.group(1))
+    m = re.search(r"\.(\d+)\.", name)
+    return int(m.group(1)) if m else None
+
+
+def _pack_aliases(vname, target_names):
+    """All alias matches for vname in target_names (either naming direction).
+    Exact match is handled by callers first; this only fires on a miss."""
+    hits = []
+    for st_suf, gg_suf in _ROLE_ALIASES:
+        for t in target_names:
+            st_v = vname.endswith(st_suf)
+            gg_v = vname.endswith(gg_suf)
+            st_t = t.endswith(st_suf)
+            gg_t = t.endswith(gg_suf)
+            if (st_v and gg_t) or (gg_v and st_t):
+                if _block_index(vname) == _block_index(t) and t not in hits:
+                    hits.append(t)
+    return hits
+
+
+def _role_key(name):
+    """(block_index, trailing_role) canonical key for same-format matching.
+    Trailing role is everything after the block number (e.g.
+    'self_attn.o_proj.weight'); unblocked names fall back to their last two
+    components (e.g. 'embed_tokens.weight'). The .weight/.bias suffix stays
+    in the key so a bias never matches a weight. The block pattern is
+    left-guarded so it never fires inside a word (e.g. 'torch.0')."""
+    import re
+    m = re.search(r"(?<![A-Za-z0-9_])(?:layers|layer|blk|blks|blocks|h)\.(\d+)\b", name)
+    if m:
+        return (int(m.group(1)), name[m.end():].strip("."))
+    m = re.search(r"\.(\d+)\.", name)
+    if m:
+        return (int(m.group(1)), name[m.end():].strip("."))
+    parts = name.split(".")
+    return (None, ".".join(parts[-2:]))
+
+
+def _same_role(vname, target_names):
+    """Targets sharing vname's (block, trailing role). Cross-format pairs
+    (ST suffix vs GGUF suffix) never collide here — _ROLE_ALIASES owns those.
+    Only fires on a miss; callers gate on elem-count and uniqueness."""
+    want = _role_key(vname)
+    return [t for t in target_names if _role_key(t) == want]
+
+
+def _cast_gguf_pack(target, out_path, items, args, op):
+    """Single-pass pack cast onto GGUF. items: [(vf32, vref, meta, vraw, vqtype)]."""
+    import numpy as np
+    from gguf import GGUFReader
+    reader = GGUFReader(target)
+    arch = _read_gguf_arch(reader)
+    varch = (items[0][2] or {}).get("architecture") if items else None
+    _confirm_arch_mismatch(varch, arch, args)
+    _names = [t.name for t in reader.tensors]
+    _counts = {}
+    for t in reader.tensors:
+        try:
+            n = 1
+            for d in t.shape:
+                n *= int(d)
+            _counts[t.name] = n
+        except Exception:
+            pass
+    _map = _resolve_pack_targets([(ref.name, ref.shape) for (_, ref, _, _, _) in items],
+                                 _names, target, _counts)
+    repl = {}
+    for vf32, vref, meta, vraw, vqtype in items:
+        target_tensor = next(t for t in reader.tensors if t.name == _map[vref.name])
+        tname = target_tensor.name
+        logical = tuple(reversed(tuple(int(x) for x in target_tensor.shape)))
+        q_head, out_qtype = _gguf_fuse_one(target, target_tensor, tname, logical, vf32, vref, meta, args, op, vraw=vraw, vqtype=vqtype)
+        repl[tname] = (q_head, out_qtype)
+    _gguf_write_repl(target, reader, arch, repl, out_path, args, op)
+
+
+def _resolve_pack_targets(pairs, target_names, target, counts=None):
+    """Map every voice tensor to a target tensor (exact, else one alias,
+    else one same-role same-format match).
+    Resolves ALL up front so a pack fails once with every miss — never
+    fix-forward one at a time. Same-size targets are offered as hints only.
+    pairs: [(voice_name, voice_shape)]; counts: {target_name: elem_count}.
+    Voice shapes are logical-as-is (GgufSource.ref already reverses);
+    only elem-counts are compared, so transposes pass and nothing double-flips."""
+    def _want(vshape):
+        if vshape is None:
+            return None
+        n = 1
+        for d in vshape:
+            n *= int(d)
+        return n
+    mapping, misses = {}, []
+    for vname, vshape in pairs:
+        if vname in target_names:
+            mapping[vname] = vname
+            continue
+        cands = _pack_aliases(vname, target_names)
+        if len(cands) == 1:
+            mapping[vname] = cands[0]
+            _note(f"  Aliased '{vname}' → '{cands[0]}' ({target} naming).")
+        elif len(cands) > 1:
+            misses.append(f"  '{vname}' is ambiguous: {', '.join(cands)}")
+        else:
+            roles = [t for t in _same_role(vname, target_names)
+                     if _want(vshape) is None or counts is None
+                     or counts.get(t, _want(vshape)) == _want(vshape)]
+            if len(roles) == 1:
+                mapping[vname] = roles[0]
+                _note(f"  Aliased '{vname}' → '{roles[0]}' (same role).")
+                continue
+            if len(roles) > 1:
+                misses.append(f"  '{vname}' is ambiguous: {', '.join(roles)}")
+                continue
+            hint = ""
+            if counts is not None and vshape is not None:
+                same = [t for t in target_names if counts.get(t) == _want(vshape)][:3]
+                if same:
+                    hint = f" (same size: {', '.join(same)})"
+            misses.append(f"  '{vname}' not found{hint}")
+    if misses:
+        _fail(f"  ✗ {len(misses)} tensor(s) have no match in target {target}:\n"
+              + "\n".join(misses)
+              + "\n  Voicepack requires exact match (not mapping to another tensor).")
+    return mapping
+
+
+def _cast_pack(target, src_path, out_path, args, op, excludes=(), meta=None):
+    """Cast every tensor in a pack file onto target (minus excludes).
+    GGUF and safetensors targets each get one write pass (repl-dict fused first).
+    Delta marker on the pack is detected once and threaded into every tensor."""
+    src = open_source(str(src_path))
+    all_names = [n for n in src.names() if n != "delta.voice.marker"]
+    for e in excludes:
+        if e not in all_names and not any(e in n for n in all_names):
+            _warn(f"  --exclude '{e}' not in pack (has {len(all_names)} tensors). Ignoring.")
+
+    resolved_ex = set()
+    for e in excludes:
+        if e in all_names:
+            resolved_ex.add(e)
+        else:
+            _m = [n for n in all_names if e in n]
+            if len(_m) == 1:
+                resolved_ex.add(_m[0])
+    to_cast = [n for n in all_names if n not in resolved_ex]
+    if not to_cast:
+        _fail("  ✗ --exclude removes all tensors. Nothing to cast.")
+    _step(f"Casting {len(to_cast)} tensors from {Path(src_path).name} onto {Path(target).name}…")
+    if resolved_ex:
+        _note(f"Excluding {len(resolved_ex)}: {', '.join(sorted(resolved_ex))}")
+    is_delta_file = str(src_path).endswith(".safetensors") and _is_delta_safetensors(str(src_path))
+    if is_delta_file:
+        _note("Detected delta voice — fusing style (delta + head)…")
+    if meta is None and is_delta_file:
+        meta = {"type": "delta", "source": str(src_path)}
+    items = []
+    for i, tname in enumerate(to_cast):
+        f32, ref, raw, qtype = _load_tensor(src_path, tname, _src=src)
+        _step(f"[{i+1}/{len(to_cast)}] {tname} ({ref.dtype} {tuple(ref.shape)})…")
+        items.append((f32, ref, meta, raw, qtype))
+    if _is_gguf_file(target):
+        _cast_gguf_pack(target, out_path, items, args, op)
+        return
+    _header, _tensors = read_safetensors(target)
+    _st_names = list(_tensors.keys())
+    _st_counts = {}
+    for _n, _info in _tensors.items():
+        try:
+            _c = 1
+            for _d in _info["shape"]:
+                _c *= int(_d)
+            _st_counts[_n] = _c
+        except Exception:
+            pass
+    _st_map = _resolve_pack_targets([(ref.name, ref.shape) for (_, ref, _, _, _) in items],
+                                    _st_names, target, _st_counts)
+    repl = {}
+    for f32, ref, m, raw, qtype in items:
+        tname, data, tdtype, tshape = _cast_st_prepare(target, _tensors, f32, ref, m, args,
+                                                      vraw=raw, vqtype=qtype, strict_target=True,
+                                                      target_name=_st_map[ref.name])
+        repl[tname] = (data, tdtype, tshape)
+    _step(f"Replacing {len(repl)} tensors in {Path(target).name}…")
+    _safetensors_write_repl(target, repl, out_path)
+    file_size = os.path.getsize(out_path)
+    log_operation({"op": op, "target": target, "format": "safetensors",
+                   "tensors": [(n, d) for n, (_b, d, _s) in repl.items()],
+                   "output": out_path, "status": "ok"})
+    _ok(f"Done → {out_path}")
+    for n, (_b, d, _s) in repl.items():
+        _say(f"  Tensor '{n}' replaced at {d} ({file_size/1e6:.1f} MB total).")
+
+
+def _parse_tensor_list(args):
+    # Tensor positionals (get/cast tensors...), with comma-split for shell convenience.
+    raw = getattr(args, "tensors", None) or []
+    if isinstance(raw, str):
+        raw = [raw]
+    # Split comma-separated entries, strip, drop empties.
+    out = []
+    for r in raw:
+        if r is None:
+            continue
+        for part in str(r).split(","):
+            part = part.strip()
+            if part:
+                out.append(part)
+    return out
+
+
+def _parse_exclude_list(args):
+    raw = getattr(args, "excludes", None) or getattr(args, "exclude", None) or []
+    if isinstance(raw, str):
+        raw = [raw]
+    out = []
+    for r in (raw or []):
+        for part in str(r).split(","):
+            part = part.strip()
+            if part:
+                out.append(part)
+    return out
+
+
+def _resolve_one_tensor(req, names):
+    # Exact match first, then single substring match, else fail. Returns resolved name.
+    if req in names:
+        return req
+    matches = [n for n in names if req and req in n]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        _fail(f"  ✗ '{req}' is ambiguous: {', '.join(matches[:8])}…")
+    _fail(f"  ✗ Tensor '{req}' not found. Try one of: {', '.join(names[:10])}")
+
+
+def _tensor_src_meta(src_path):
+    """File-level delta detection for the tensor path (the marker lives in the file; no voice.json)."""
+    if str(src_path).endswith(".safetensors"):
+        try:
+            if _is_delta_safetensors(str(src_path)):
+                return {"type": "delta", "source": str(src_path)}
+        except Exception:
+            pass
+    return None
+
+
+def _load_tensor(path, name=None, _src=None):
+    src = _src if _src is not None else open_source(str(path))
+    names = src.names()
+    if not names:
+        _fail(f"  ✗ No tensors found in {path}.")
+    if name is None:
+        name = "output.weight" if "output.weight" in names else names[0]
+
+    if name not in names:
+        matches = [n for n in names if name in n]
+        if len(matches) == 1:
+            name = matches[0]
+        else:
+            _fail(f"  ✗ Tensor '{name}' not found in {path}.")
+    ref = src.ref(name)
+    if src.kind == "gguf" and _is_ggml_quant(ref.dtype):
+        return None, ref, src.read_raw(name), ref.dtype
+    return src.read_f32(name), ref, None, None
+
+

vlib/ctx.py

@@ -0,0 +1,33 @@
+"""Shared constants and globals: single definition for paths, version, verbosity."""
+
+from pathlib import Path
+
+
+VOICES_DIR = Path.home() / ".voices"
+
+
+HF_TOKEN_PATH = VOICES_DIR / ".hf_token"
+
+
+OPERATIONS_LOG = VOICES_DIR / "operations.log"
+
+
+REPORTS_JSONL = VOICES_DIR / "reports.jsonl"
+
+
+REPORTS_OUTBOX = VOICES_DIR / "outbox"
+
+
+REPORTS_DATASET_ID = "Wiself/voice-reports"
+
+
+REPORTS_REMOTE_PREFIX = "data/reports-"
+
+
+VERSION = "3.0"
+
+
+DTYPE_BYTES = {"F32": 4, "F16": 2, "BF16": 2}
+
+
+VERBOSE = False

vlib/delta.py

@@ -0,0 +1,340 @@
+"""Delta computation (voice minus base) and base resolution."""
+
+from pathlib import Path
+import json
+import os
+import struct
+import sys
+import time
+from vlib.ui import _fail, _noninteractive, _progress_pref, _say, _transform, _warn
+from vlib.net import _fmt_eta
+from vlib.tensors import _is_delta_safetensors, _is_ggml_quant, decode_to_f32, dtype_bytes, read_safetensors
+from vlib.sources import _detect_base, _normalize_hf_repo, _public_source, open_source
+from vlib.fetch import _resolve_output_name, _source_arch
+from vlib.registry import _assert_not_symlink, _iter_voices, _read_meta
+
+
+def _choose_voice(args):
+    voices = []
+    for d in _iter_voices():
+        meta = _read_meta(d / "voice.json")
+        if meta:
+            voices.append((d.name, meta))
+    if not voices:
+        _fail("  ✗ No voices stored yet. Use 'voice get <model>' to save one.")
+    _say("  Available voices:")
+    for i, (dirname, meta) in enumerate(voices, 1):
+        _say(f"  {i}. {meta.get('name', dirname)} — {meta.get('source_hf_model', meta.get('source', '—'))}")
+    try:
+        choice = input(f"  Choose voice [1-{len(voices)}]: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    if not choice.isdigit() or not (1 <= int(choice) <= len(voices)):
+        _fail("  ✗ Invalid choice.")
+    return voices[int(choice) - 1][1].get("name", voices[int(choice) - 1][0])
+
+
+def _resolve_base(args, source_hf):
+    base_arg = getattr(args, "base", None)
+    if base_arg:
+        # allow local file/dir path as base (for manual delta)
+        p = Path(base_arg).expanduser()
+        if p.exists():
+            return str(p.resolve())
+        norm = _normalize_hf_repo(base_arg)
+        if norm is None:
+            _fail(f"  ✗ Invalid HF repo '{base_arg}'. Use org/model or a local path.")
+        return norm
+    if source_hf not in ("—", "", None) and "/" in source_hf:
+        suggested, is_multi, count, _raw = _detect_base(source_hf)
+    else:
+        suggested, is_multi, count, _raw = None, False, 0, []
+    if suggested is None:
+        if _noninteractive(args):
+            _fail("  ✗ Could not detect the base model. Use --base <org/model> --yes")
+        try:
+            entered = input("  Enter base HF repo (org/model) or local path: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            _say("  ⚠ Cancelled.")
+            sys.exit(0)
+        if not entered:
+            _fail("  ✗ Invalid base repo.")
+        p = Path(entered).expanduser()
+        if p.exists():
+            return str(p.resolve())
+        norm = _normalize_hf_repo(entered)
+        if norm is None:
+            _fail("  ✗ Invalid base repo.")
+        return norm
+    if is_multi:
+        _say(f"  Base: {suggested} ({count} candidates)")
+    else:
+        _say(f"  Base detected: {suggested}")
+    if _noninteractive(args):
+        return suggested
+    try:
+        entered = input(f"  Press enter to use {suggested}, or type another repo/path: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    if not entered:
+        return suggested
+    p = Path(entered).expanduser()
+    if p.exists():
+        return str(p.resolve())
+    norm = _normalize_hf_repo(entered)
+    return norm if norm else suggested
+
+
+def _delta_gate(args, warn_lines, phrase, fail_hint):
+    """Confirm niche delta-on-delta cases. Fails fast when non-interactive."""
+    for i, line in enumerate(warn_lines):
+        (_warn if i == 0 else _say)(line)
+    if _noninteractive(args):
+        _fail(f"  ✗ {fail_hint} (re-run interactively and type {phrase} to proceed).")
+    try:
+        ans = input(f"  Type {phrase} to continue, Enter to cancel: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        _say("  Cancelled."); sys.exit(0)
+    if ans.strip().lower() != phrase.lower():
+        _say("  Cancelled."); sys.exit(0)
+
+
+def _check_delta_gate(args, voice_path, base_path):
+    """Single gate-checker for delta-on-delta niche cases. Computes the
+    is_voice/is_base flags internally (GGUF has no marker, so non-safetensors
+    sides stay False — matches both the guarded GGUF branch and the
+    safetensors branch, where both sides are .safetensors)."""
+    is_voice_delta = _is_delta_safetensors(str(voice_path)) if str(voice_path).endswith(".safetensors") else False
+    is_base_delta = _is_delta_safetensors(str(base_path)) if str(base_path).endswith(".safetensors") else False
+    if not is_voice_delta and is_base_delta:
+        _delta_gate(args, ["  The base you gave is a delta-voice (has delta.voice.marker).",
+                           "  Deltas are meant to be applied, not used as a base.",
+                           "  normal − delta = 2*normal − style — nonsense, not a style."],
+                    "UNDO THE UNDO", "delta-on-delta needs explicit confirmation")
+    elif is_voice_delta and not is_base_delta:
+        _delta_gate(args, ["  The voice you gave is already a delta-voice.",
+                           "  Delta-on-normal is usually just style − base. You are doing delta − normal = style − 2*normal."],
+                    "DOUBLE DIP", "delta-on-delta needs explicit confirmation")
+    elif is_voice_delta and is_base_delta:
+        _delta_gate(args, ["  ✨ Congratulations — you have discovered a hidden feature",
+                           "     The voice and base are both delta-voices.",
+                           "     delta − delta = style difference of style differences."],
+                    "BIG BRAIN", "delta-on-delta needs explicit confirmation")
+
+
+def _compute_delta(voice_path, base_path, delta_folder, delta_name, args=None):
+    # Fast path: both safetensors (no dequant, chunked, efficient for 1.4GB).
+    # Slow path: either side GGUF quant -> dequant once to F32 (unavoidable), direct numpy (efficient for <50MB tests).
+    _v_gguf = _b_gguf = False
+    # Chunk seam resolves through the voice facade (not vlib.tensors): the suite
+    # patches voice._DELTA_CHUNK_ELEMS / voice._gguf_raw_slice_to_f32, so the
+    # slow path must honor the facade namespace. Local import: voice imports us.
+    import voice as _facade
+    try:
+        v_hdr, v_tensors = read_safetensors(str(voice_path))
+    except Exception:
+        _v_gguf = True
+        v_hdr = v_tensors = None
+    try:
+        b_hdr, b_tensors = read_safetensors(str(base_path))
+    except Exception:
+        _b_gguf = True
+        b_hdr = b_tensors = None
+    if _v_gguf or _b_gguf:
+        import numpy as np
+        # Resolve tensor names via open_source (handles GGUF + safetensors uniformly).
+        v_src = open_source(str(voice_path))
+        b_src = open_source(str(base_path))
+        v_names = [n for n in v_src.names() if n != "delta.voice.marker"]
+        b_names = [n for n in b_src.names() if n != "delta.voice.marker"]
+        if not v_names or not b_names:
+            _fail("  ✗ No tensors found for delta.")
+        # Match by exact name: every voice tensor needs a same-named base tensor.
+        # Output head first for deterministic order, then voice order.
+        try:
+            arch, cfg = _source_arch(v_src)
+            _cand = _resolve_output_name(v_src, cfg, v_names)
+        except Exception:
+            _cand = None
+        ordered = ([_cand] if _cand in v_names else []) + [n for n in v_names if n != _cand]
+        missing = [n for n in ordered if n not in b_names]
+        if missing:
+            shown = ", ".join(missing[:5]) + ("…" if len(missing) > 5 else "")
+            _fail(f"  ✗ {len(missing)} voice tensor(s) have no match in base: {shown}. Delta needs same names on both sides.")
+        pairs = [(n, n) for n in ordered]
+        _check_delta_gate(args, voice_path, base_path)
+        _assert_not_symlink(delta_folder)
+        delta_folder.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(delta_folder, 0o700)
+        except Exception:
+            pass
+        out_path = delta_folder / "voice.safetensors"
+        tmp_out = delta_folder / "voice.safetensors.tmp"
+        # Header first (offsets need shapes only), then stream one pair at a
+        # time so packs never hold every tensor in RAM at once.
+        header, off = {}, 0
+        for vname, bname in pairs:
+            vref, bref = v_src.ref(vname), b_src.ref(bname)
+            if tuple(vref.shape) != tuple(bref.shape):
+                _fail(f"  ✗ Voice tensor '{vname}' shape {tuple(vref.shape)} doesn't fit base {tuple(bref.shape)}.")
+            nbytes = 2
+            for d in vref.shape:
+                nbytes *= int(d)
+            header[vname] = {"dtype": "F16", "shape": [int(x) for x in vref.shape], "data_offsets": [off, off + nbytes]}
+            off += nbytes
+        header["delta.voice.marker"] = {"dtype": "U8", "shape": [1], "data_offsets": [off, off + 1]}
+        header["__metadata__"] = {"type": "delta", "base": _public_source(str(base_path)), "voice": _public_source(str(voice_path))}
+        hj = json.dumps(header).encode("utf-8")
+        with open(tmp_out, "wb") as out:
+            out.write(struct.pack("<Q", len(hj)))
+            out.write(hj)
+            for vname, bname in pairs:
+                vref, bref = v_src.ref(vname), b_src.ref(bname)
+                _warn(f"  Dequanting {vname} ({vref.dtype}) and base ({bref.dtype}) once to F32 for delta math (unavoidable for GGUF quant).")
+                elems = 1
+                for d in vref.shape:
+                    elems *= int(d)
+                # Within a pair, decode/dequant in _DELTA_CHUNK_ELEMS slices so peak
+                # stays O(chunk): plain sides stream raw slices; quant sides stream
+                # block-aligned raw slices (GGML_QUANT_SIZES units decode independently).
+                from gguf.constants import GGMLQuantizationType as _Q
+                from gguf.constants import GGML_QUANT_SIZES as _QS
+                v_q = _is_ggml_quant(vref.dtype)
+                b_q = _is_ggml_quant(bref.dtype)
+                v_qt = _Q[vref.dtype] if v_q else None
+                b_qt = _Q[bref.dtype] if b_q else None
+                v_bpe = 1 if v_q else dtype_bytes(vref.dtype)
+                b_bpe = 1 if b_q else dtype_bytes(bref.dtype)
+
+                def _quant_slice(src, name, qt, at, n):
+                    bs, ts = _QS[qt]
+                    b0 = at // bs
+                    b1 = (at + n + bs - 1) // bs
+                    seg = src.read_raw_slice(name, b0 * ts, (b1 - b0) * ts)
+                    return _facade._gguf_raw_slice_to_f32(seg, qt, at - b0 * bs, n)
+
+                done = 0
+                while done < elems:
+                    cur = min(_facade._DELTA_CHUNK_ELEMS, elems - done)
+                    if v_q:
+                        v_f32 = _quant_slice(v_src, vname, v_qt, done, cur)
+                    else:
+                        v_f32 = decode_to_f32(v_src.read_raw_slice(vname, done * v_bpe, cur * v_bpe),
+                                              vref.dtype, (cur,))
+                    if b_q:
+                        b_f32 = _quant_slice(b_src, bname, b_qt, done, cur)
+                    else:
+                        b_f32 = decode_to_f32(b_src.read_raw_slice(bname, done * b_bpe, cur * b_bpe),
+                                              bref.dtype, (cur,))
+                    out.write((v_f32.astype(np.float32) - b_f32.astype(np.float32)).astype("float16").tobytes())
+                    done += cur
+            out.write(b"\x01")
+            out.flush()
+            try:
+                os.fsync(out.fileno())
+            except Exception:
+                pass
+        tmp_out.replace(out_path)
+        return out_path
+    # Original chunked safetensors-safetensors path below (no dequant beyond F32 math per chunk).
+    # Match by exact name: every voice tensor needs a same-named base tensor.
+    v_keys = [k for k in v_tensors.keys() if k != "delta.voice.marker"]
+    if not v_keys:
+        _fail("  ✗ No tensors found for delta.")
+    missing = [k for k in v_keys if k not in b_tensors]
+    if missing:
+        shown = ", ".join(missing[:5]) + ("…" if len(missing) > 5 else "")
+        _fail(f"  ✗ {len(missing)} voice tensor(s) have no match in base: {shown}. Delta needs same names on both sides.")
+    pairs = [(k, k) for k in v_keys]
+    _check_delta_gate(args, voice_path, base_path)
+    with open(voice_path, "rb") as f:
+        v_hs = struct.unpack("<Q", f.read(8))[0]
+    with open(base_path, "rb") as f:
+        b_hs = struct.unpack("<Q", f.read(8))[0]
+    specs = []
+    header, off = {}, 0
+    for vname, bname in pairs:
+        vinfo, binfo = v_tensors[vname], b_tensors[bname]
+        vshape, bshape = tuple(vinfo["shape"]), tuple(binfo["shape"])
+        if vshape != bshape:
+            _fail(f"  ✗ Voice tensor '{vname}' shape {vshape} doesn't fit base {bshape}.")
+        elems = 1
+        for d in vshape:
+            elems *= int(d)
+        nbytes = elems * 2
+        header[vname] = {"dtype": "F16", "shape": list(vshape), "data_offsets": [off, off + nbytes]}
+        off += nbytes
+        specs.append({"name": vname, "vinfo": vinfo, "binfo": binfo,
+                      "v_start": 8 + v_hs + vinfo["data_offsets"][0],
+                      "b_start": 8 + b_hs + binfo["data_offsets"][0],
+                      "v_bpe": dtype_bytes(vinfo["dtype"]), "b_bpe": dtype_bytes(binfo["dtype"]),
+                      "elems": elems})
+    total_elems = off // 2
+    marker_name = "delta.voice.marker"
+    header[marker_name] = {"dtype": "U8", "shape": [1], "data_offsets": [off, off + 1]}
+    header["__metadata__"] = {"type": "delta", "base": _public_source(str(base_path)), "voice": _public_source(str(voice_path))}
+    hj = json.dumps(header).encode("utf-8")
+    _assert_not_symlink(delta_folder)
+    delta_folder.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(delta_folder, 0o700)
+    except Exception:
+        pass
+    out_path = delta_folder / "voice.safetensors"
+    tmp_out = delta_folder / "voice.safetensors.tmp"
+    chunk = 1 << 20
+    total_bytes = total_elems * 2
+    t0 = time.time()
+    last = [0.0]
+    def _delta_progress(force=False):
+        now = time.time()
+        if not force and now - last[0] < 0.25 and processed < total_elems:
+            return
+        last[0] = now
+        elapsed = now - t0 or 1e-6
+        mbps = (processed * 2) / elapsed / 1e6
+        pct = processed / total_elems * 100 if total_elems else 100
+        remain = total_bytes - processed * 2
+        eta = _fmt_eta(remain, mbps)
+        msg = f"  → crafting delta {pct:3.0f}% · {processed*2/1e6:.0f}/{total_bytes/1e6:.0f} MB · {mbps:.1f} MB/s · {eta}  "
+        sys.stdout.write(_transform(msg) + ("\n" if _progress_pref() else "\r"))
+        sys.stdout.flush()
+    with open(voice_path, "rb") as fv, open(base_path, "rb") as fb, open(tmp_out, "wb") as out:
+        out.write(struct.pack("<Q", len(hj)))
+        out.write(hj)
+        processed = 0
+        _delta_progress(force=True)
+        for spec in specs:
+            fv.seek(spec["v_start"])
+            fb.seek(spec["b_start"])
+            vinfo, binfo = spec["vinfo"], spec["binfo"]
+            v_bpe, b_bpe = spec["v_bpe"], spec["b_bpe"]
+            done = 0
+            while done < spec["elems"]:
+                cur = min(chunk, spec["elems"] - done)
+                v_raw = fv.read(cur * v_bpe)
+                b_raw = fb.read(cur * b_bpe)
+                if len(v_raw) != cur * v_bpe or len(b_raw) != cur * b_bpe:
+                    sys.stdout.write("\n")
+                    _fail(f"  ✗ Short read during delta compute ({spec['name']}).")
+                v_f32 = decode_to_f32(v_raw, vinfo["dtype"], (cur,))
+                b_f32 = decode_to_f32(b_raw, binfo["dtype"], (cur,))
+                delta_f16 = (v_f32 - b_f32).astype("float16")
+                out.write(delta_f16.tobytes())
+                done += cur
+                processed += cur
+                _delta_progress()
+        _delta_progress(force=True)
+        sys.stdout.write("\n")
+        # marker byte for auto-detect (delta.voice.marker)
+        out.write(b"\x01")
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+    tmp_out.replace(out_path)
+    return out_path

vlib/fetch.py

@@ -0,0 +1,188 @@
+"""Fetching tensors from sources into local bytes."""
+
+from pathlib import Path
+import json
+import os
+from vlib import ctx
+from vlib.ui import _fail, _now_iso, _step, _warn
+from vlib.net import _cleanup_tmp, _safe_id, download_range
+from vlib.tensors import _is_ggml_quant, _is_quant_fetched, _write_safetensors_streaming, _write_single_tensor_gguf, encode_from_f32, write_safetensors
+from vlib.sources import _hf_config, _public_source, detect_output_tensor, largest_2d
+
+
+def _source_arch(source):
+    if source.kind == "safetensors":
+        cfg = _hf_config(source.repo) if source.repo else None
+        if cfg:
+            arch = (cfg.get("architectures") or [None])[0] or cfg.get("model_type")
+        else:
+            arch = None
+        return arch, cfg
+    source._load()
+    if getattr(source, "_reader", None) is not None:
+        for f in source._reader.fields.values():
+            if f.name == "general.architecture":
+                try:
+                    v = f.parts[f.data[0]]
+                    return (v.decode() if isinstance(v, bytes) else str(v)), None
+                except Exception:
+                    return None, None
+    return (source._remote[0] if source._remote else None), None
+
+
+def _resolve_output_name(source, config, names):
+    if source.kind == "gguf":
+        for n in ("output.weight", "token_embd.weight"):
+            if n in names:
+                return n
+        n = detect_output_tensor(names, config)
+        if n:
+            return n
+    else:
+        n = detect_output_tensor(names, config)
+        if n:
+            return n
+    shapes = {n: source.ref(n).shape for n in names}
+    return largest_2d(names, shapes)
+
+
+def _stream_safetensors_tensor(source, name, dest_path):
+    """Stream a safetensors tensor's raw bytes to dest_path. Returns byte count."""
+    if source.path:
+        hs, tensors = source._local()
+        begin, end = tensors[name]["data_offsets"]
+        with open(source.path, "rb") as src, open(dest_path, "wb") as out:
+            src.seek(8 + hs + begin)
+            remaining = end - begin
+            while remaining:
+                b = src.read(min(8 << 20, remaining))
+                if not b:
+                    break
+                out.write(b)
+                remaining -= len(b)
+        return end - begin
+    url, hs, tensors = source._shard_info(name)
+    begin, end = tensors[name]["data_offsets"]
+    import shutil
+    combined = download_range(url, 8 + hs + begin, 8 + hs + end - 1, dest_path.parent, None, label=name)
+    shutil.move(str(combined), str(dest_path))
+    return end - begin
+
+
+def _fetch_tensor(source, name, tmp_dir):
+    """Return (kind, raw_path, data, dtype, shape) for one tensor.
+    kind == 'file' → raw bytes at raw_path; kind == 'bytes' → data holds bytes.
+    GGML-quantized tensors keep their exact raw blocks (no requant)."""
+    ref = source.ref(name)
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+    if source.kind == "safetensors":
+        raw_path = tmp_dir / "raw.bin"
+        n = _stream_safetensors_tensor(source, name, raw_path)
+        return ("file", raw_path, n, ref.dtype, ref.shape)
+    if _is_ggml_quant(ref.dtype):
+        # passthrough: exact quant blocks, stored in a single-tensor GGUF artifact
+        raw_path = tmp_dir / "raw.bin"
+        n = _stream_gguf_tensor(source, name, raw_path)
+        return ("file", raw_path, n, ref.dtype, ref.shape)
+    f32 = source.read_f32(name)
+    # Preserve original precision family: BF16 stays BF16 (not F16 downconvert),
+    # F32 stays F32, F16 stays F16. BF16->F32->BF16 round-trip is exact.
+    _rd = ref.dtype.upper()
+    if _rd in ("F32", "FP32"):
+        dtype = "F32"
+    elif _rd in ("BF16", "BF16E8M"):
+        dtype = "BF16"
+    else:
+        dtype = "F16"
+    return ("bytes", None, encode_from_f32(f32, dtype), dtype, ref.shape)
+
+
+def _stream_gguf_tensor(source, name, dest_path):
+    """Stream a GGUF tensor's exact raw blocks to dest_path. Returns byte count."""
+    import shutil
+    import numpy as np
+    if source.path:
+        source._load()
+        for t in source._reader.tensors:
+            if t.name == name:
+                with open(dest_path, "wb") as out:
+                    raw = t.data.tobytes() if t.data.dtype == np.uint8 else memoryview(t.data).cast("B").tobytes()
+                    out.write(raw)
+                return t.n_bytes
+        raise KeyError(name)
+    dims, gtype, data_offset, n_bytes = source._remote[2][name]
+    start = source._remote[1] + data_offset
+    combined = download_range(source.url, start, start + n_bytes - 1, dest_path.parent, None, label=name)
+    shutil.move(str(combined), str(dest_path))
+    return n_bytes
+
+
+def _write_fetched(fetched, tensor_name, out_path):
+    """Write a fetched tensor to a standalone artifact (gguf when quantized)."""
+    kind, raw_path, data, dtype, shape = fetched
+    if _is_quant_fetched(fetched):
+        if not str(out_path).endswith(".gguf"):
+            out_path = str(out_path)[:-len(".safetensors")] + ".gguf" if str(out_path).endswith(".safetensors") else str(out_path) + ".gguf"
+        _write_single_tensor_gguf(tensor_name, raw_path, raw_path.stat().st_size, dtype, shape, str(out_path))
+        return Path(out_path)
+    tmp = str(out_path) + ".tmp"
+    if kind == "file":
+        _write_safetensors_streaming(tensor_name, str(raw_path), raw_path.stat().st_size, dtype, shape, tmp)
+    else:
+        write_safetensors({tensor_name: (data, dtype, shape)}, tmp)
+    os.replace(tmp, str(out_path))
+    return Path(out_path)
+
+
+def _write_voicepack_json(out_path, source_id, pack):
+    """Provenance sidecar for a voicepack: source + per-tensor names/shapes/dtypes.
+    Written next to the pack file (same stem, .json suffix)."""
+    meta = {
+        "source": _public_source(source_id),
+        "tensors": [{"name": n, "shape": [int(x) for x in v[2]], "dtype": v[1]}
+                    for n, v in pack.items()],
+        "downloaded_at": _now_iso(),
+    }
+    jpath = Path(str(out_path)).with_suffix(".json")
+    jtmp = jpath.parent / (jpath.name + ".tmp")
+    jtmp.write_text(json.dumps(meta, indent=2) + "\n")
+    jtmp.replace(jpath)
+    return jpath
+
+
+def _fetch_pack(source, source_id, resolved):
+    """Fetch each resolved tensor's raw bytes. Returns pack {name: (bytes, dtype, shape)}.
+    Shared by get --multi and pack: always safetensors (GGUF quants dequant once with a warning)."""
+    pack = {}
+    for tname in resolved:
+        ref = source.ref(tname)
+        _step(f"Extracting {tname} ({ref.dtype} {tuple(ref.shape)})…")
+        tmp_dir = ctx.VOICES_DIR / ".parts" / _safe_id(source_id, tname)
+        try:
+            fetched = _fetch_tensor(source, tname, tmp_dir)
+        except Exception as e:
+            _fail(f"  ✗ Could not extract tensor {tname}: {e}")
+        kind, raw_path, data, dtype, shape = fetched
+        try:
+            if kind == "file":
+                # safetensors raw file: read bytes directly (preserves BF16/F16/F32).
+                with open(str(raw_path), "rb") as f:
+                    b = f.read()
+                pack[tname] = (b, dtype, tuple(shape))
+            else:
+                # bytes already encoded (F32/F16/BF16 preserved).
+                pack[tname] = (data, dtype, tuple(shape))
+            # If fetched was GGUF quant passthrough, _fetch_tensor returns
+            # ("file", raw, n, qtype, shape) with quant dtype — dequant once for safetensors pack.
+            if _is_ggml_quant(dtype):
+                _warn(f"  {tname} is {dtype} quant — dequanting once to F32 for voicepack.safetensors (unavoidable, safetensors has no quant).")
+                try:
+                    f32 = source.read_f32(tname)
+                    pack[tname] = (f32.astype("float32").tobytes(), "F32", tuple(shape))
+                except Exception as e:
+                    _fail(f"  ✗ Could not dequant {tname} for pack: {e}")
+        finally:
+            _cleanup_tmp(tmp_dir)
+    if not pack:
+        _fail("  ✗ Nothing to pack.")
+    return pack

vlib/net.py

@@ -0,0 +1,451 @@
+"""HTTP, auth, retries, and ranged downloads."""
+
+from pathlib import Path
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+from vlib import ctx
+from vlib.ui import _fail, _note, _progress_pref, _say, _transform
+
+
+_HF_TOKEN_CACHE = {"tok": None, "ts": 0.0}
+
+
+def _get_hf_token():
+    # cache 60s to avoid file thrash on hot path
+    now = time.time()
+    if now - _HF_TOKEN_CACHE["ts"] < 60 and _HF_TOKEN_CACHE["tok"] is not None:
+        return _HF_TOKEN_CACHE["tok"]
+    tok = None
+    for k in ("HF_TOKEN", "HF_HUB_TOKEN", "HUGGING_FACE_HUB_TOKEN"):
+        v = os.environ.get(k)
+        if v and v.strip().startswith("hf_"):
+            tok = v.strip()
+            break
+    if tok is None:
+        for p in (ctx.HF_TOKEN_PATH, Path.home() / ".cache" / "huggingface" / "token", Path.home() / ".huggingface" / "token"):
+            try:
+                if p.exists():
+                    t = p.read_text().strip()
+                    if t.startswith("hf_"):
+                        tok = t
+                        break
+            except Exception:
+                continue
+    _HF_TOKEN_CACHE["tok"] = tok
+    _HF_TOKEN_CACHE["ts"] = now
+    return tok
+
+
+_HF_TRUSTED_HOSTS = frozenset({"huggingface.co", "cdn-lfs.huggingface.co", "cdn-lfs-us-1.huggingface.co"})
+
+
+from functools import lru_cache
+
+
+@lru_cache(maxsize=256)
+def _is_hf_url(url):
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except Exception:
+        return False
+    if host in _HF_TRUSTED_HOSTS:
+        return True
+    return host == "huggingface.co" or host.endswith(".huggingface.co")
+
+
+def _hf_auth_headers(url, extra=None):
+    """Auth + UA. Never sends Authorization to non-HF hosts; never overwrites caller header for HF either."""
+    h = {"User-Agent": "voice/2.0"}
+    if extra:
+        # Strip caller Authorization if target is not HF - prevents token leak to arbitrary URL
+        if not _is_hf_url(url) and "Authorization" in extra:
+            extra = {k: v for k, v in extra.items() if k != "Authorization"}
+        h.update(extra)
+    if "Authorization" not in h:
+        tok = _get_hf_token()
+        if tok and _is_hf_url(url):
+            h["Authorization"] = f"Bearer {tok}"
+    # If caller supplied Authorization for non-HF, drop it
+    if "Authorization" in h and not _is_hf_url(url):
+        del h["Authorization"]
+    return h
+
+
+class _PreserveAuthRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, hdrs, newurl):
+        result = super().redirect_request(req, fp, code, msg, hdrs, newurl)
+        if result is None:
+            return None
+        if _is_hf_url(newurl):
+            if "Authorization" not in result.headers:
+                tok = _get_hf_token()
+                if tok:
+                    result.add_header("Authorization", f"Bearer {tok}")
+        else:
+            # stdlib forwards the original headers across hosts: strip the token
+            # (bridge/CDN URLs are pre-signed, so it is never needed there either)
+            try:
+                result.remove_header("Authorization")
+            except Exception:
+                pass
+        return result
+
+
+urllib.request.install_opener(urllib.request.build_opener(_PreserveAuthRedirectHandler()))
+
+
+def _parse_retry_after(headers):
+    try:
+        v = headers.get("Retry-After") or headers.get("retry-after")
+        return int(str(v).split(",")[0].strip()) if v is not None else None
+    except Exception:
+        return None
+
+
+def _bounded_retry_after(headers, fallback, cap=30):
+    """Retry-After with a cap: a 429 must never look like a hang (e.g. Retry-After: 3600)."""
+    try:
+        ra = _parse_retry_after(headers)
+        wait = ra if ra is not None else fallback
+    except Exception:
+        wait = fallback
+    try:
+        wait = float(wait)
+    except Exception:
+        wait = float(fallback)
+    if wait < 0:
+        wait = float(fallback)
+    return min(wait, cap)
+
+
+def _timeout(base):
+    try:
+        env = int(os.environ.get("HF_HUB_DOWNLOAD_TIMEOUT", "0"))
+        return max(base, env) if env > 0 else base
+    except Exception:
+        return base
+
+
+def http_range(url, start, end, timeout=60):
+    for attempt in range(3):
+        hdrs = _hf_auth_headers(url, {"Range": f"bytes={start}-{end}"})
+        try:
+            with urllib.request.urlopen(urllib.request.Request(url, headers=hdrs), timeout=_timeout(timeout)) as resp:
+                if resp.status == 429 and attempt < 2:
+                    wait = _bounded_retry_after(resp.headers, 1.5 * (2 ** attempt))
+                    if wait >= 5:
+                        _note(f"  Rate limited (429) — waiting {wait:.0f}s before retry…")
+                    time.sleep(wait)
+                    continue
+                if resp.status not in (200, 206):
+                    raise urllib.error.HTTPError(url, resp.status, f"status {resp.status}", resp.headers, None)
+                return resp.read(), resp.status, resp.headers.get("ETag")
+        except urllib.error.HTTPError as e:
+            if e.code == 429 and attempt < 2:
+                wait = _bounded_retry_after(getattr(e, "headers", None) or {}, 1.5 * (2 ** attempt))
+                if wait >= 5:
+                    _note(f"  Rate limited (429) — waiting {wait:.0f}s before retry…")
+                time.sleep(wait)
+                continue
+            raise
+
+
+def http_get_json(url, timeout=30):
+    req = urllib.request.Request(url, headers=_hf_auth_headers(url))
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        try:
+            e.close()  # else the response fp dangles until GC (ResourceWarning)
+        except Exception:
+            pass
+        raise
+
+
+def _safe_id(model_id, shard_url=""):
+    mid = re.sub(r"[^a-z0-9._-]", "_", model_id.strip().lower().replace("..", "_").replace("/", "__").replace("\\", "_").replace(":", "_"))
+    mid = re.sub(r"_+", "_", mid).strip("_")[:120]
+    if shard_url:
+        shard = re.sub(r"[^a-z0-9._-]", "_", shard_url.split("/")[-1].replace(".safetensors", "").replace(".gguf", "")).lower()[:40]
+        return f"{mid}__{shard}"
+    return mid
+
+
+def _acquire_parts_lock(part_dir):
+    """Best-effort cross-process lock for .parts. Returns lock path or None."""
+    lock = part_dir / ".lock"
+    try:
+        # O_EXCL to avoid double acquisition
+        fd = os.open(str(lock), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        try:
+            os.write(fd, str(os.getpid()).encode())
+        finally:
+            os.close(fd)
+        return lock
+    except FileExistsError:
+        try:
+            # stale lock (>10 min) - reclaim
+            if time.time() - lock.stat().st_mtime > 600:
+                lock.unlink(missing_ok=True)
+                fd = os.open(str(lock), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+                os.close(fd)
+                return lock
+        except Exception:
+            pass
+        return None
+    except Exception:
+        return None
+
+
+def download_range(url, abs_start, abs_end, part_dir, etag, label="", n_parts=None):
+    import threading
+
+    total = abs_end - abs_start + 1
+    part_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(part_dir.parent, 0o700)
+    except Exception:
+        pass
+    meta_path = part_dir / "meta.json"
+
+    old_etag = None
+    if meta_path.exists():
+        try:
+            old_etag = json.loads(meta_path.read_text()).get("etag")
+        except Exception:
+            old_etag = None
+    # acquire lock BEFORE writing meta so racers can't interleave etag/url
+    _parts_lock = _acquire_parts_lock(part_dir)
+    try:
+        meta_path.write_text(json.dumps({"url": url, "abs_start": abs_start, "total": total, "etag": etag}, indent=2))
+    except Exception:
+        pass
+
+    try:
+        import shutil
+        free = shutil.disk_usage(part_dir).free
+        if free < int(total * 1.25):
+            _fail(f"  ✗ Not enough disk space: need {total*1.25/1e9:.1f} GB, free {free/1e9:.1f} GB.")
+    except SystemExit:
+        raise
+    except Exception:
+        pass
+
+    if n_parts is None:
+        n_parts = 8 if total > 512 * 1024 * 1024 else (4 if total > 128 * 1024 * 1024 else 1)
+    chunk_total = total // n_parts
+    ranges = []
+    for i in range(n_parts):
+        s = i * chunk_total
+        e = (s + chunk_total - 1) if i < n_parts - 1 else total - 1
+        ranges.append((abs_start + s, abs_start + e, part_dir / f"chunk_{i:03d}.part", e - s + 1))
+
+    downloaded = 0
+    for _rs, _re, p, csz in ranges:
+        if p.exists():
+            try:
+                sz = p.stat().st_size
+                # If ETag changed (or one side unknown), invalidate stale chunk
+                if old_etag != etag and (old_etag is not None or etag is not None):
+                    p.unlink(missing_ok=True)
+                    continue
+                if sz > csz:
+                    p.unlink(missing_ok=True)
+                    continue
+                downloaded += sz
+            except Exception:
+                pass
+
+    t0 = time.time()
+    lock = threading.RLock()  # reentrant: progress() also takes it, and runs inside locked regions
+    stop = threading.Event()  # set on fatal error / interrupt: workers wind down, partials kept
+    errors = []
+    last = [0.0]
+
+    def progress(force=False):
+        now = time.time()
+        with lock:
+            cur_downloaded = downloaded
+        if not force and now - last[0] < 0.25 and cur_downloaded < total:
+            return
+        last[0] = now
+        elapsed = now - t0 or 1e-6
+        mbps = cur_downloaded / elapsed / 1e6
+        pct = cur_downloaded / total * 100 if total else 100
+        remain = total - cur_downloaded
+        eta = _fmt_eta(remain, mbps)
+        msg = f"  → {label} {pct:3.0f}% · {cur_downloaded/1e6:.0f}/{total/1e6:.0f} MB · {mbps:.1f} MB/s · {eta}  "
+        sys.stdout.write(_transform(msg) + ("\n" if _progress_pref() else "\r"))
+        sys.stdout.flush()
+
+    # show 0% immediately so user sees waiting + speed
+    progress(force=True)
+
+    def chunk(r_start, r_end, p, csz):
+        nonlocal downloaded
+        existing = p.stat().st_size if p.exists() else 0
+        if existing == csz:
+            return  # already complete (counted in pre-scan); re-requesting would 416
+        eff = r_start + existing
+        for attempt in range(3):
+            if stop.is_set():
+                return
+            try:
+                hdrs = _hf_auth_headers(url, {"Range": f"bytes={eff}-{r_end}"})
+                if etag:
+                    hdrs["If-Match"] = etag
+                with urllib.request.urlopen(urllib.request.Request(url, headers=hdrs), timeout=_timeout(120)) as resp:
+                    if resp.status not in (200, 206):
+                        raise urllib.error.HTTPError(url, resp.status, "bad status", None, None)
+                    if resp.status == 200 and (r_end - r_start + 1) != total:
+                        # multi-part chunk but server ignored Range: body is wrong data — fail fast
+                        _fail(f"  ✗ Server ignored the Range request for {label or url} (got 200, need 206). Resume unsupported — try again later.")
+                    if existing and resp.status == 200:
+                        # server ignored Range - we already counted existing in downloaded, correct it
+                        with lock:
+                            downloaded -= existing
+                        p.unlink(missing_ok=True)
+                        existing = 0
+                        eff = r_start
+                    mode = "ab" if existing else "wb"
+                    with open(p, mode) as f:
+                        while not stop.is_set():
+                            b = resp.read(8 << 20)
+                            if not b:
+                                break
+                            f.write(b)
+                            with lock:
+                                downloaded += len(b)
+                                progress()
+                        f.flush()
+                        try:
+                            os.fsync(f.fileno())
+                        except Exception:
+                            pass
+                final = p.stat().st_size if p.exists() else 0
+                if final != csz and attempt < 2:
+                    existing = final
+                    eff = r_start + final
+                    time.sleep(0.5 * (attempt + 1))
+                    continue
+                if final != csz:
+                    raise OSError(f"{p.name} incomplete {final}/{csz}")
+                return
+            except urllib.error.HTTPError as e:
+                if attempt < 2:
+                    wait = _bounded_retry_after(getattr(e, "headers", None) or {}, 0.7 * (2 ** attempt))
+                    if wait >= 5:
+                        _note(f"  Rate limited ({e.code}) — waiting {wait:.0f}s before retry…")
+                    time.sleep(wait)
+                    if p.exists():
+                        existing = p.stat().st_size
+                        eff = r_start + existing
+                    continue
+                raise
+            except (urllib.error.URLError, TimeoutError, OSError):
+                if attempt < 2:
+                    time.sleep(0.7 * (2 ** attempt))
+                    if p.exists():
+                        existing = p.stat().st_size
+                        eff = r_start + existing
+                    continue
+                raise
+        raise OSError(f"{p.name} failed after 3 retries")
+
+    def worker(rs, re_, p, csz):
+        try:
+            chunk(rs, re_, p, csz)
+        except SystemExit as e:
+            errors.append(e)  # _fail() already printed the reason
+            stop.set()
+        except Exception as e:  # noqa: BLE001 — transported to main thread below
+            errors.append(e)
+            stop.set()
+
+    try:
+        if n_parts == 1:
+            rs, re_, p, csz = ranges[0]
+            chunk(rs, re_, p, csz)
+        else:
+            # daemon threads: Ctrl-C returns instantly, partial chunks kept for resume
+            threads = [threading.Thread(target=worker, args=(rs, re_, p, csz), daemon=True)
+                       for rs, re_, p, csz in ranges]
+            for t in threads:
+                t.start()
+            while any(t.is_alive() for t in threads):
+                for t in threads:
+                    t.join(timeout=0.25)
+                    if stop.is_set():
+                        break
+                if stop.is_set():
+                    break
+            if errors:
+                raise errors[0]
+    except KeyboardInterrupt:
+        stop.set()
+        sys.stdout.write("\n")
+        _fail(f"  ✗ Download cancelled ({downloaded/1e6:.0f}/{total/1e6:.0f} MB kept). Run again to resume.")
+    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError, OSError):
+        sys.stdout.write("\n")
+        _fail(f"  ✗ Download interrupted ({downloaded/1e6:.0f}/{total/1e6:.0f} MB kept). Run again to resume.")
+    except Exception as e:
+        sys.stdout.write("\n")
+        if ctx.VERBOSE:
+            import traceback
+            _say(traceback.format_exc())
+        _fail(f"  ✗ Download failed: {e}")
+
+    # ensure 100% with speed is shown before combining
+    progress(force=True)
+    for _rs, _re, p, csz in ranges:
+        try:
+            if p.stat().st_size != csz:
+                _fail(f"  ✗ Incomplete download ({p.name}). Run again to resume.")
+        except Exception:
+            _fail(f"  ✗ Missing chunk {p.name}. Run again to resume.")
+    combined = part_dir / "combined.part"
+    with open(combined, "wb") as out:
+        for _rs, _re, p, _csz in ranges:
+            with open(p, "rb") as inp:
+                while True:
+                    b = inp.read(8 << 20)
+                    if not b:
+                        break
+                    out.write(b)
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+    # clean up lock
+    try:
+        if '_parts_lock' in locals() and _parts_lock and _parts_lock.exists():
+            _parts_lock.unlink(missing_ok=True)
+    except Exception:
+        pass
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    return combined
+
+
+def _fmt_eta(remaining, mbps):
+    if mbps < 1e-6:
+        return "--:--"
+    sec = int(remaining / (mbps * 1e6))
+    return f"{sec}s" if sec < 60 else f"{sec//60}m {sec%60}s"
+
+
+def _cleanup_tmp(tmp_dir):
+    try:
+        if tmp_dir.exists():
+            import shutil
+            shutil.rmtree(tmp_dir)
+    except Exception:
+        pass

vlib/pack.py

@@ -0,0 +1,76 @@
+"""Head-only voice-pack preset (unused by the CLI)."""
+import argparse
+import json
+import urllib.error
+from pathlib import Path
+
+from vlib import ctx
+from vlib.fetch import _fetch_pack, _resolve_output_name, _source_arch
+from vlib.sources import (_family, _hf_config, _public_source,
+                          _slugify_voice_name, open_source)
+from vlib.tensors import write_safetensors
+from vlib.ui import _fail, _note, _now_iso, _say, _step
+
+
+def _resolve_pack_tensors(source, repo, config, names):
+    """Head-only voice-pack preset. Embed/norm/blocks stay manual
+    (voice get <repo> <tensors...>).
+    Config is the source config with _hf_config fallback. Miss fails loud."""
+    if config is None and getattr(source, "repo", None):
+        config = _hf_config(source.repo)
+    head = _resolve_output_name(source, config, names)
+    if head is None:
+        _fail(f"  ✗ pack: no output head found in '{repo}'.")
+    return [head]
+
+
+def cmd_pack(args):
+    repo = args.repo.strip().rstrip("/")
+    if not repo:
+        _fail("  ✗ Enter a model name — for example: voice pack google/gemma-3-1b")
+    _step(f"Finding the voice pack in {repo}…")
+    try:
+        source = open_source(repo)
+        names = source.names()
+        if not names:
+            _fail(f"  ✗ No tensors found in '{repo}'.")
+        arch, config = _source_arch(source)
+    except urllib.error.HTTPError as e:
+        _fail(f"  ✗ Model '{repo}' was not found or is not accessible ({e.code}).")
+    except Exception as e:
+        if ctx.VERBOSE:
+            import traceback
+            _say(traceback.format_exc())
+        _fail(f"  ✗ Could not reach the model. Check your connection ({type(e).__name__}).")
+
+    _step("Resolving voice-pack tensors…")
+    resolved = _resolve_pack_tensors(source, repo, config, names)
+    for tname in resolved:
+        _note(f"  {tname}")
+    # Fetch via the same multi path as get --multi, then save flat in the
+    # registry through the existing add machinery (no new storage format).
+    pack = _fetch_pack(source, repo, resolved)
+    slug = _slugify_voice_name(repo.split("/")[-1].split("@")[0].split(":")[0].replace(".gguf", "").replace(".safetensors", ""))
+    name = f"pack-{slug}"
+    import tempfile, shutil
+    stage = Path(tempfile.mkdtemp(prefix="voicepack-stage-"))
+    try:
+        st_path = stage / "voice.safetensors"
+        write_safetensors(pack, str(st_path))
+        js_path = stage / "voice.json"
+        js_path.write_text(json.dumps({
+            "name": name,
+            "source": _public_source(repo),
+            "source_format": source.kind,
+            "tensors": [{"name": n, "shape": [int(x) for x in pack[n][2]], "dtype": pack[n][1]}
+                        for n in resolved if n in pack],
+            "architecture": arch,
+            "family": _family(arch),
+            "downloaded_at": _now_iso(),
+        }, indent=2) + "\n")
+        from vlib.cmds_voices import cmd_add
+        cmd_add(argparse.Namespace(safetensors=str(st_path), json=str(js_path), name=name,
+                                   yes=getattr(args, "yes", False),
+                                   non_interactive=getattr(args, "non_interactive", False)))
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)

vlib/registry.py

@@ -0,0 +1,323 @@
+"""Voice registry, ops log, and write guards."""
+
+from pathlib import Path
+import json
+import os
+import sys
+import time
+from vlib import ctx
+from vlib.ui import _confirm, _fail, _noninteractive, _say, _warn
+from vlib.tensors import _is_gguf_file, _is_quant_fetched, _write_safetensors_streaming, _write_single_tensor_gguf, write_safetensors
+from vlib.sources import _NAME_RULES, _sanitize_voice_name, _slugify_voice_name
+
+
+def log_operation(record):
+    record = {"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), **record}
+    try:
+        ctx.VOICES_DIR.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(ctx.VOICES_DIR, 0o700)
+        except Exception:
+            pass
+        _assert_not_symlink(ctx.OPERATIONS_LOG)
+        with open(ctx.OPERATIONS_LOG, "a") as f:
+            f.write(json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n")
+            try:
+                f.flush()
+                os.fsync(f.fileno())
+            except Exception:
+                pass
+        try:
+            os.chmod(ctx.OPERATIONS_LOG, 0o600)
+        except Exception:
+            pass
+        try:
+            dirfd = os.open(str(ctx.VOICES_DIR), os.O_DIRECTORY)
+            try:
+                os.fsync(dirfd)
+            finally:
+                os.close(dirfd)
+        except Exception:
+            pass
+    except Exception:
+        if ctx.VERBOSE:
+            _warn("could not write operation log")
+
+
+def _atomic_jsonl_append(path, record):
+    """Append one JSON line atomically with flock + fsync. Optimised: single chmod, cached JSON."""
+    path = Path(path)
+    # fast path: parent exists, avoid mkdir/chmod churn
+    if not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(path.parent, 0o700)
+        except Exception:
+            pass
+    if not path.exists():
+        try:
+            fd = os.open(str(path), os.O_WRONLY | os.O_CREAT, 0o600)
+            os.close(fd)
+        except Exception:
+            pass
+    else:
+        # occasional chmod drift check, not every append
+        try:
+            if oct(path.stat().st_mode & 0o777) != "0o600":
+                os.chmod(path, 0o600)
+        except Exception:
+            pass
+    _assert_not_symlink(path)
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with open(path, "a") as f:
+        try:
+            import fcntl
+            fcntl.flock(f, fcntl.LOCK_EX)
+            locked = True
+        except Exception:
+            locked = False
+        try:
+            f.write(line)
+            f.flush()
+            try:
+                os.fsync(f.fileno())
+            except Exception:
+                pass
+        finally:
+            if locked:
+                try:
+                    import fcntl
+                    fcntl.flock(f, fcntl.LOCK_UN)
+                except Exception:
+                    pass
+    try:
+        dirfd = os.open(str(path.parent), os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+
+
+def _write_outbox(report_id, record):
+    ctx.REPORTS_OUTBOX.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(ctx.REPORTS_OUTBOX, 0o700)
+    except Exception:
+        pass
+    _assert_not_symlink(ctx.REPORTS_OUTBOX)
+    out_path = ctx.REPORTS_OUTBOX / f"{report_id}.json"
+    _assert_not_symlink(out_path)
+    tmp = out_path.with_suffix(".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, (json.dumps(record, ensure_ascii=False) + "\n").encode("utf-8"))
+        try:
+            os.fsync(fd)
+        except Exception:
+            pass
+    finally:
+        os.close(fd)
+    tmp.replace(out_path)
+    try:
+        dirfd = os.open(str(ctx.REPORTS_OUTBOX), os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+    return out_path
+
+
+def _append_report(record):
+    _atomic_jsonl_append(ctx.REPORTS_JSONL, record)
+    _write_outbox(record["report_id"], record)
+    log_operation({"op": "report", "report_id": record["report_id"], "status": "ok", "voice": record.get("voice"), "target": record.get("target")})
+
+
+def _iter_voices():
+    if not ctx.VOICES_DIR.exists():
+        return []
+    return [d for d in sorted(ctx.VOICES_DIR.iterdir(), key=lambda p: p.name.lower())
+            if d.is_dir() and not d.name.startswith(".") and d.name != "base"]
+
+
+def _registry_resolve(name_or_path):
+    p = Path(name_or_path).expanduser()
+    if p.is_file():
+        return p, None
+    if p.is_dir():
+        for fname in ("voice.safetensors", "voice.gguf"):
+            if (p / fname).exists():
+                return p / fname, _read_meta(p / "voice.json")
+    target = name_or_path.strip().lower()
+    for d in _iter_voices():
+        if d.name.lower() == target:
+            for fname in ("voice.safetensors", "voice.gguf"):
+                if (d / fname).exists():
+                    return d / fname, _read_meta(d / "voice.json")
+    return None, None
+
+
+def _read_meta(json_path):
+    try:
+        return json.loads(json_path.read_text()) if json_path.exists() else None
+    except Exception:
+        return None
+
+
+def _registry_name_exists(name):
+    target = name.strip().lower()
+    return any(d.name.lower() == target for d in _iter_voices())
+
+
+def _registry_folder(name):
+    return ctx.VOICES_DIR / name.strip().lower()
+
+
+def _assert_not_symlink(path):
+    # Resolve-first, fail-closed. The old code compared raw strings
+    # (str.startswith): a sibling such as ".voices2" counted as "inside"
+    # ".voices", uninspected parents were skipped by the same prefix test,
+    # and any resolve failure was swallowed (fail-open). Now: resolve before
+    # any comparison, test membership with real path relations, walk every
+    # component below VOICES_DIR, and refuse when resolution itself fails.
+    # Scope: registry paths (under VOICES_DIR). Unrelated user paths (e.g. an
+    # explicit --out in /tmp) keep the old behavior: direct-symlink check only,
+    # since the user chose them and system roots above them may legitimately
+    # be links. TOCTOU (link swapped between check and write) is out of scope:
+    # local CLI, self-owned dir.
+    try:
+        p = Path(path)
+        abs_p = p.absolute()
+        norm = Path(os.path.normpath(abs_p))
+        base_abs = ctx.VOICES_DIR.absolute()
+        base_res = ctx.VOICES_DIR.resolve()
+        rp = p.resolve()
+        if p.is_symlink():
+            _fail(f"  ✗ Refusing to write through symlink: {path}")
+        prefix_hit = str(abs_p).startswith(str(base_abs))
+        inside = norm == base_abs or base_abs in norm.parents
+        if inside or prefix_hit:
+            # every component from the base down must be symlink-free; a
+            # prefix-sibling (".voices2") has no relative leg to walk, but it
+            # still faces the containment check below.
+            if inside:
+                cur = base_abs
+                for part in norm.relative_to(base_abs).parts:
+                    cur = cur / part
+                    if cur.is_symlink():
+                        _fail(f"  ✗ Refusing to write through symlink: {cur}")
+            if rp != base_res and base_res not in rp.parents:
+                _fail(f"  ✗ Refusing to write outside VOICES_DIR: {path}")
+    except SystemExit:
+        raise
+    except Exception:
+        _fail(f"  ✗ Refusing to write through unresolvable path: {path}")
+
+
+def _write_voice(folder, tensor_name, fetched, meta):
+    _assert_not_symlink(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(folder, 0o700)
+    except Exception:
+        pass
+    _assert_not_symlink(folder)
+    kind, raw_path, data, dtype, shape = fetched
+    if _is_quant_fetched(fetched):
+        fpath = folder / "voice.gguf"
+        tmp = folder / "voice.gguf.tmp"
+        _write_single_tensor_gguf(tensor_name, raw_path, raw_path.stat().st_size, dtype, shape, str(tmp))
+    else:
+        fpath = folder / "voice.safetensors"
+        tmp = folder / "voice.safetensors.tmp"
+        if kind == "file":
+            _write_safetensors_streaming(tensor_name, str(raw_path), raw_path.stat().st_size, dtype, shape, str(tmp))
+        else:
+            write_safetensors({tensor_name: (data, dtype, shape)}, str(tmp))
+    tmp.replace(fpath)
+    try:
+        os.chmod(fpath, 0o600)
+    except Exception:
+        pass
+    meta = dict(meta)
+    meta["artifact_format"] = "gguf" if _is_quant_fetched(fetched) else "safetensors"
+    meta["ggml_type"] = dtype if _is_quant_fetched(fetched) else None
+    meta["bytes"] = fpath.stat().st_size
+    jtmp = folder / "voice.json.tmp"
+    # atomic 0600 json write
+    fd = os.open(str(jtmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, (json.dumps(meta, indent=2) + "\n").encode("utf-8"))
+        try:
+            os.fsync(fd)
+        except Exception:
+            pass
+    finally:
+        os.close(fd)
+    jtmp.replace(folder / "voice.json")
+    return fpath
+
+
+def _resolve_name(args, default_name):
+    provided = getattr(args, "name", None)
+    if provided and str(provided).strip():
+        name = str(provided).strip()
+        if _sanitize_voice_name(name) is None:
+            _fail(f"  ✗ Invalid name '{name}'. {_NAME_RULES}")
+        return name
+    default_slug = _slugify_voice_name(default_name)
+    if _noninteractive(args):
+        return default_slug
+    try:
+        entered = input(f"  → Name the voice or press enter to use [{default_slug}]: ").strip()
+        name = entered or default_slug
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    if _sanitize_voice_name(name) is None:
+        _fail(f"  ✗ Invalid name '{name}'. {_NAME_RULES}")
+    return name
+
+
+def _out_path(args, target, voice_arg):
+    if getattr(args, "out", None):
+        out = args.out
+        # jail: resolve but allow any absolute path user explicitly requested; block symlink traversal
+        if out.endswith(("/", os.sep)) or os.path.isdir(out) or not os.path.splitext(out)[1]:
+            out = os.path.join(out, f"{_stem(voice_arg)}-{_stem(target)}{'.gguf' if _is_gguf_file(target) else '.safetensors'}")
+        # normalize
+        out = os.path.abspath(out)
+        return out
+    # sane default: ~/Voiced/<voice>-<model>/<voice>-<model>.gguf (not alongside target)
+    # avoids overwriting and keeps Voiced folder tidy
+    voiced_base = Path.home() / "Voiced"
+    sub = f"{_stem(voice_arg)}-{_stem(target)}"
+    ext = ".gguf" if _is_gguf_file(target) else ".safetensors"
+    return str(voiced_base / sub / f"{sub}{ext}")
+
+
+def _stem(p):
+    return os.path.splitext(os.path.basename(p))[0]
+
+
+def _check_overwrite(out_path, args):
+    if os.path.islink(out_path):
+        _fail(f"  ✗ Refusing to write through symlink: {out_path}")
+    if os.path.exists(out_path):
+        if _noninteractive(args) and not getattr(args, "yes", False):
+            _fail(f"  ✗ Output '{out_path}' exists. Use --yes to overwrite in non-interactive mode.")
+        if not _confirm(f"  Output '{out_path}' already exists. Overwrite? [y/N]: ", args):
+            _say("  Cancelled.")
+            sys.exit(0)
+    out_dir = os.path.dirname(os.path.abspath(out_path))
+    if out_dir and os.path.islink(out_dir):
+        _fail(f"  ✗ Refusing to write through symlink: {out_dir}")
+    if out_dir and not os.path.isdir(out_dir):
+        try:
+            os.makedirs(out_dir, exist_ok=True)
+        except Exception:
+            _fail(f"  ✗ Could not create folder \"{out_dir}\".")

vlib/reports.py

@@ -0,0 +1,469 @@
+"""Local reports and community sharing."""
+
+from pathlib import Path
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from vlib import ctx
+from vlib.ui import _noninteractive, _now_iso, _ok, _say, _step, _warn
+from vlib.net import _get_hf_token, _parse_retry_after
+from vlib.tensors import _is_gguf_file, read_safetensors
+from vlib.sources import _family, _public_source, detect_output_tensor, largest_2d
+from vlib.registry import _append_report, _iter_voices, _read_meta, _registry_resolve
+
+
+def _hash_file(path):
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            b = f.read(8 << 20)
+            if not b:
+                break
+            h.update(b)
+    return h.hexdigest()
+
+
+def _sanitize_note(s):
+    if s is None:
+        return None
+    s = str(s).replace("\r", " ").replace("\n", " ").replace("\x00", " ")
+    s = re.sub(r"\s+", " ", s).strip()
+    if not s:
+        return None
+    # strip CSV injection prefixes
+    if s and s[0] in "=+@-":
+        s = "'" + s
+    if len(s) > 240:
+        s = s[:239] + "…"
+    return s
+
+
+def _sanitize_reporter(s):
+    if not s:
+        return None
+    s = re.sub(r"[^A-Za-z0-9._-]", "_", str(s).strip())[:64].strip("_")
+    return s or None
+
+
+def _prompt_share(args, preview=None):
+    if getattr(args, "no_push", False):
+        return False
+    if getattr(args, "yes", False):
+        return True
+    if _noninteractive(args):
+        return False
+    if preview:
+        _say(f"  Will share: {preview}")
+    try:
+        ans = input("  Leave a breadcrumb to help the next person? [y/N] (N): ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    return ans in ("y", "yes")
+
+
+def _push_reports_batch(records):
+    """Batch push: group by shard, single fetch+upload per shard. Returns pushed count.
+    Non-collaborators lack write access to Wiself/voice-reports → fallback to PR (create_pr=True).
+    Fixes tempfile.mktemp racy API → mkstemp 0600; 3 retries on 429/409/412.
+    Note: download-modify-upload still racy for direct pushes (two owners racing may lose);
+    dedup on report_id softens it, and PR path eliminates race for crowd (each PR is isolated)."""
+    import time, tempfile
+    if not records:
+        return 0
+    tok = _get_hf_token()
+    if not tok:
+        _warn("  No HF token — saved to outbox only. Run: voice auth")
+        return 0
+    try:
+        from huggingface_hub import HfApi
+        from huggingface_hub import CommitOperationAdd
+        api = HfApi(token=tok)
+    except Exception as e:
+        _warn(f"  huggingface_hub not available ({e}) — kept in outbox.")
+        return 0
+    try:
+        api.create_repo(repo_id=ctx.REPORTS_DATASET_ID, repo_type="dataset", exist_ok=True)
+    except Exception:
+        pass
+    from collections import defaultdict
+    by_shard = defaultdict(list)
+    for r in records:
+        shard = f"{ctx.REPORTS_REMOTE_PREFIX}{r['ts'][:7]}.jsonl"
+        by_shard[shard].append(r)
+    pushed = 0
+    for shard, recs in by_shard.items():
+        for attempt in range(3):
+            try:
+                existing = ""
+                try:
+                    from huggingface_hub import hf_hub_download
+                    tmp = hf_hub_download(repo_id=ctx.REPORTS_DATASET_ID, repo_type="dataset", filename=shard, token=tok)
+                    existing = Path(tmp).read_text(encoding="utf-8", errors="replace")
+                except Exception:
+                    existing = ""
+                # parse existing_ids properly (not substring) for correct dedup
+                existing_ids = set()
+                if existing:
+                    for line in existing.splitlines():
+                        if not line.strip():
+                            continue
+                        try:
+                            existing_ids.add(json.loads(line).get("report_id"))
+                        except Exception:
+                            continue
+                # headroom check per Tim Cook: warn if shard near 10k
+                if len(existing_ids) > 10000:
+                    _warn(f"  Shard {shard} has {len(existing_ids)} reports — consider rotation (reports-YYYY-MM-2).")
+                todo = [r for r in recs if r["report_id"] not in existing_ids]
+                if not todo:
+                    for r in recs:
+                        try:
+                            (ctx.REPORTS_OUTBOX / f"{r['report_id']}.json").unlink(missing_ok=True)
+                        except Exception:
+                            pass
+                    pushed += len(recs)
+                    break
+                if not existing:
+                    new_content = "\n".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) for r in todo) + "\n"
+                else:
+                    if not existing.endswith("\n"):
+                        existing += "\n"
+                    new_content = existing + "\n".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) for r in todo) + "\n"
+                # mkstemp 0600, not deprecated mktemp
+                fd_tmp, tmp_path = tempfile.mkstemp(prefix="voice-report-")
+                tmpf = Path(tmp_path)
+                try:
+                    os.write(fd_tmp, new_content.encode("utf-8"))
+                    try:
+                        os.fsync(fd_tmp)
+                    except Exception:
+                        pass
+                finally:
+                    try:
+                        os.close(fd_tmp)
+                    except Exception:
+                        pass
+                try:
+                    os.chmod(tmpf, 0o600)
+                except Exception:
+                    pass
+                # try direct push first; on 403 (no write access) fallback to PR
+                try:
+                    api.upload_file(path_or_fileobj=str(tmpf), path_in_repo=shard, repo_id=ctx.REPORTS_DATASET_ID, repo_type="dataset", commit_message=f"report batch {len(todo)} -> {shard}")
+                except Exception as e_direct:
+                    is_403 = False
+                    try:
+                        from huggingface_hub.utils import HfHubHTTPError as _HE
+                        if isinstance(e_direct, _HE) and getattr(e_direct.response, "status_code", None) == 403:
+                            is_403 = True
+                        elif "403" in str(e_direct) or "Forbidden" in str(e_direct):
+                            is_403 = True
+                    except Exception:
+                        pass
+                    if is_403:
+                        _step("  No write access — creating pull request…")
+                        api.create_commit(
+                            repo_id=ctx.REPORTS_DATASET_ID,
+                            repo_type="dataset",
+                            operations=[CommitOperationAdd(path_in_repo=shard, path_or_fileobj=str(tmpf))],
+                            commit_message=f"report batch {len(todo)} -> {shard} ({todo[0]['report_id'][:8]}…)",
+                            create_pr=True,
+                        )
+                        _ok("  PR opened — thank you! Maintainer will merge shortly.")
+                    else:
+                        raise
+                try:
+                    tmpf.unlink(missing_ok=True)
+                except Exception:
+                    pass
+                for r in todo:
+                    try:
+                        (ctx.REPORTS_OUTBOX / f"{r['report_id']}.json").unlink(missing_ok=True)
+                    except Exception:
+                        pass
+                pushed += len(todo)
+                break
+            except Exception as e:
+                try:
+                    from huggingface_hub.utils import HfHubHTTPError as _HE
+                    code = getattr(getattr(e, "response", None), "status_code", None)
+                    if isinstance(e, _HE) and code in (429, 409, 412):
+                        ra = _parse_retry_after(getattr(e.response, "headers", {}) or {})
+                        time.sleep(ra or (0.7 * (2 ** attempt)))
+                        continue
+                    # 403 already handled via PR above; other 403 should not retry as direct
+                    if isinstance(e, _HE) and code == 403:
+                        # if PR also failed, keep in outbox
+                        _warn(f"  Push failed for {shard} (403 Forbidden) — kept in outbox. PR fallback also failed.")
+                        break
+                except Exception:
+                    pass
+                if attempt < 2 and isinstance(e, (urllib.error.URLError, TimeoutError, OSError)):
+                    time.sleep(0.7 * (2 ** attempt))
+                    continue
+                if attempt >= 2:
+                    if ctx.VERBOSE:
+                        import traceback
+                        _say(traceback.format_exc())
+                    _warn(f"  Push failed for {shard} ({type(e).__name__}: {e}) — kept in outbox.")
+                    break
+                time.sleep(0.7 * (2 ** attempt))
+    return pushed
+
+
+def _push_report(record):
+    return _push_reports_batch([record]) == 1
+
+
+def _last_operation():
+    try:
+        if not ctx.OPERATIONS_LOG.exists():
+            return None
+        # read last non-empty line
+        with open(ctx.OPERATIONS_LOG, "rb") as f:
+            f.seek(0, 2)
+            size = f.tell()
+            if size == 0:
+                return None
+            # read tail 8KB
+            read = min(size, 8192)
+            f.seek(size - read)
+            tail = f.read().decode("utf-8", "replace").strip().splitlines()
+            for line in reversed(tail):
+                if not line.strip():
+                    continue
+                try:
+                    rec = json.loads(line)
+                    op = rec.get("op")
+                    if op:
+                        return op
+                except Exception:
+                    continue
+    except Exception:
+        pass
+    return None
+
+
+def cmd_report(args):
+    msg = _sanitize_note(getattr(args, "message", None))
+    voice_arg = getattr(args, "voice", None)
+    import uuid, platform
+    report_id = uuid.uuid4().hex
+    ts = _now_iso()
+    # sanitize voice/target early for CSV safety
+    voice_name = _sanitize_note(voice_arg.strip()) if voice_arg and voice_arg.strip() else None
+    target_raw = getattr(args, "target", None)
+    target_basename = _sanitize_note(Path(target_raw).name) if target_raw else None
+    # auto-pull voice provenance
+    voice_meta = None
+    try:
+        if voice_arg:
+            vp, vm = _registry_resolve(voice_arg)
+            if vp and vp.exists():
+                if vm is None:
+                    vm = _read_meta(Path(vp).parent / "voice.json")
+                voice_meta = dict(vm or {})
+                if "tensor_sha256" not in voice_meta and vp.exists():
+                    try:
+                        voice_meta["tensor_sha256"] = _hash_file(str(vp))
+                    except Exception:
+                        pass
+            else:
+                # fallback: most recent voice if requested name not found
+                voices = sorted([d for d in _iter_voices() if (d / "voice.json").exists()], key=lambda p: p.stat().st_mtime, reverse=True)
+                if voices:
+                    vm = _read_meta(voices[0] / "voice.json")
+                    if vm:
+                        voice_meta = dict(vm)
+                        if not voice_name:
+                            voice_name = _sanitize_note(vm.get("name") or voices[0].name)
+        else:
+            # zero flags: auto-pull most recent voice for full traceability
+            voices = sorted([d for d in _iter_voices() if (d / "voice.json").exists()], key=lambda p: p.stat().st_mtime, reverse=True)
+            if voices:
+                vm = _read_meta(voices[0] / "voice.json")
+                if vm:
+                    voice_meta = dict(vm)
+                    if not voice_name:
+                        voice_name = _sanitize_note(vm.get("name") or voices[0].name)
+    except Exception:
+        pass
+    # auto-probe target file if exists
+    target_info = None
+    if target_raw and Path(target_raw).expanduser().exists():
+        try:
+            p = Path(target_raw).expanduser()
+            if _is_gguf_file(str(p)):
+                from gguf import GGUFReader
+                r = GGUFReader(str(p))
+                arch = None
+                for fld in r.fields.values():
+                    if fld.name == "general.architecture":
+                        try:
+                            v = fld.parts[fld.data[0]]
+                            if isinstance(v, bytes):
+                                arch = v.decode()
+                            elif hasattr(v, "tobytes"):
+                                try:
+                                    arch = v.tobytes().decode()
+                                except Exception:
+                                    arch = str(v)
+                            else:
+                                arch = str(v)
+                            arch = arch.strip("\x00").strip()
+                        except Exception:
+                            pass
+                        break
+                # find output tensor
+                tname = None
+                for pref in ("output.weight", "token_embd.weight"):
+                    for t in r.tensors:
+                        if t.name == pref:
+                            tname = t.name
+                            break
+                    if tname:
+                        break
+                shape = None
+                dtype = None
+                if tname:
+                    for t in r.tensors:
+                        if t.name == tname:
+                            shape = list(reversed([int(x) for x in t.shape]))
+                            dtype = t.tensor_type.name
+                            break
+                target_info = {"basename": target_basename, "format": "gguf", "tensor_name": tname, "architecture": arch, "family": _family(arch), "shape": shape, "dtype": dtype}
+            else:
+                # try safetensors probe (header only)
+                try:
+                    hdr, tens = read_safetensors(str(p))
+                    # pick output tensor
+                    tname = detect_output_tensor(list(tens.keys()), None) or largest_2d(list(tens.keys()), {k: v["shape"] for k, v in tens.items()})
+                    info = tens.get(tname) if tname else None
+                    target_info = {"basename": target_basename, "format": "safetensors", "tensor_name": tname, "shape": list(info["shape"]) if info else None, "dtype": info["dtype"] if info else None}
+                except Exception:
+                    target_info = {"basename": target_basename, "format": "safetensors"}
+        except Exception:
+            pass
+    if target_info is None and target_basename:
+        target_info = {"basename": target_basename}
+    # env enrichment
+    try:
+        import numpy as _np
+        np_ver = getattr(_np, "__version__", None)
+    except Exception:
+        np_ver = None
+    try:
+        import gguf as _gg
+        gg_ver = getattr(_gg, "__version__", "installed")
+    except Exception:
+        gg_ver = None
+    env_info = {"voice_ver": ctx.VERSION, "python": platform.python_version(), "platform": platform.platform(), "numpy": np_ver, "gguf": gg_ver}
+    operation = getattr(args, "operation", None) or _last_operation() or "report"
+    record = {
+        "v": 2,
+        "report_id": report_id,
+        "ts": ts,
+        "voice": voice_name,
+        "voice_meta": voice_meta,
+        "target": target_basename,
+        "target_meta": target_info,
+        "operation": operation,
+        "status": "ok",
+        "message": msg,
+        "env": env_info,
+    }
+    # keep backward compat flat fields for old dataset readers
+    if voice_meta:
+        record["voice_source"] = _public_source(voice_meta.get("source_hf_model") or voice_meta.get("source"))
+        record["voice_tensor"] = voice_meta.get("tensor_name")
+        record["voice_dtype"] = voice_meta.get("dtype")
+        record["voice_shape"] = voice_meta.get("shape")
+    reporter = _sanitize_reporter(getattr(args, "reporter", None))
+    if reporter:
+        record["reporter"] = reporter
+    # auto-reporter from HF token if available (opt-in via --reporter not set)
+    if "reporter" not in record:
+        # do not auto-fill PII; keep null unless user opted
+        pass
+    # validate size
+    try:
+        rec_json = json.dumps(record, ensure_ascii=False)
+        if len(rec_json) > 4096:
+            _warn("  Note too large — truncating.")
+            record["message"] = _sanitize_note((msg or "")[:240])
+    except Exception:
+        pass
+    _append_report(record)
+    _ok(f"Thanks for noting — saved locally ({report_id[:8]}…) → {ctx.REPORTS_JSONL}")
+    _say(f"  Outbox: {ctx.REPORTS_OUTBOX / (report_id + '.json')} (private, stays until you choose to share)")
+    # also handle --sync of pending
+    if getattr(args, "sync", False):
+        pending = sorted(ctx.REPORTS_OUTBOX.glob("*.json"))
+        if not pending:
+            _say("  No pending reports to sync.")
+            return
+        _step(f"Syncing {len(pending)} pending report(s)…")
+        recs = []
+        for p in pending:
+            try:
+                recs.append(json.loads(p.read_text()))
+            except Exception as e:
+                _warn(f"  Could not read {p.name}: {e}")
+        if recs:
+            n = _push_reports_batch(recs)
+            _ok(f"Synced {n}/{len(recs)} report(s).")
+        return
+    # warm preview — what will be shared
+    preview = None
+    try:
+        pv = voice_name or (voice_meta.get("name") if voice_meta else None) or "—"
+        pt = (voice_meta.get("tensor_name") if voice_meta else None) or (target_info.get("tensor_name") if target_info else None) or "—"
+        ps = voice_meta.get("shape") if voice_meta and voice_meta.get("shape") else (target_info.get("shape") if target_info else None)
+        pd = voice_meta.get("dtype") if voice_meta and voice_meta.get("dtype") else (target_info.get("dtype") if target_info else None)
+        pv_str = f"voice: {pv}, tensor: {pt}"
+        if ps:
+            pv_str += f" {ps}"
+        if pd:
+            pv_str += f" {pd}"
+        if target_basename:
+            pv_str += f", target: {target_basename}"
+            if target_info and target_info.get("family"):
+                pv_str += f" {target_info.get('family')}"
+        preview = pv_str
+    except Exception:
+        preview = None
+    should_push = _prompt_share(args, preview=preview)
+    if should_push:
+        _step("Sharing to community to help others…")
+        ok = _push_report(record)
+        if ok:
+            _ok("Shared to community — thank you! Helps the next person.")
+            pending = sorted(ctx.REPORTS_OUTBOX.glob("*.json"))
+            if pending:
+                recs = []
+                for p in pending:
+                    try:
+                        recs.append(json.loads(p.read_text()))
+                    except Exception:
+                        continue
+                if recs:
+                    _step(f"Syncing {len(recs)} pending report(s)…")
+                    _push_reports_batch(recs)
+            # headroom warning
+            try:
+                sz = ctx.REPORTS_JSONL.stat().st_size if ctx.REPORTS_JSONL.exists() else 0
+                if sz > 50 * 1024 * 1024:
+                    _warn(f"  reports.jsonl {sz/1e6:.1f} MB — consider archiving (rotation to reports-YYYY-MM.jsonl).")
+                if len(list(ctx.REPORTS_OUTBOX.glob("*.json"))) > 5000:
+                    _warn("  Outbox >5000 pending — run voice report --sync --yes to flush.")
+            except Exception:
+                pass
+        else:
+            _warn("  Share pending — will retry on next report or voice doctor.")
+    else:
+        _say("  Saved locally. Outbox retained for later push (rerun with --yes to share).")

vlib/sources.py

@@ -0,0 +1,507 @@
+"""Model sources: naming heuristics, HF metadata, source objects."""
+
+from pathlib import Path
+import json
+import re
+import struct
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+from vlib import ctx
+from vlib.ui import _fail, _note
+from vlib.net import _hf_auth_headers, http_get_json, http_range
+from vlib.tensors import _gguf_raw_to_f32, _gguf_tensor_f32, _is_gguf_file, _parse_gguf_header, decode_to_f32
+
+
+OUTPUT_ALIASES = (
+    "lm_head.weight", "output.weight", "transformer.output_layer.weight",
+    "output_layer.weight", "embed_out.weight",
+)
+
+
+EMBEDDING_ALIASES = (
+    "model.embed_tokens.weight", "embed_tokens.weight",
+    "transformer.embedding.word_embeddings.weight", "wte.weight", "word_embeddings.weight",
+)
+
+
+def _family(arch):
+    a = (arch or "").lower()
+    if "glm" in a or "chatglm" in a:
+        return "GLM"
+    if "gemma4" in a:
+        return "Gemma 4"
+    if "gemma" in a:
+        return "Gemma"
+    if "qwen" in a:
+        return "Qwen"
+    if "llama" in a:
+        return "Llama"
+    if "gpt2" in a or "gptneo" in a:
+        return "GPT"
+    if "opt" in a:
+        return "OPT"
+    return arch or "unknown"
+
+
+def _nested(cfg, *keys):
+    for k in keys:
+        if isinstance(cfg.get(k), (int, str, list)):
+            return cfg[k]
+    tc = cfg.get("text_config") or {}
+    for k in keys:
+        if isinstance(tc.get(k), (int, str, list)):
+            return tc[k]
+    return None
+
+
+def detect_output_tensor(names, config):
+    if not names:
+        return None
+    for alias in OUTPUT_ALIASES:
+        if alias in names:
+            return alias
+    for n in names:
+        if any(a in n for a in ("lm_head", "output_layer", "embed_out")) and n.endswith("weight"):
+            return n
+    tie = config.get("tie_word_embeddings") if config else None
+    if tie is True:
+        for alias in EMBEDDING_ALIASES:
+            if alias in names:
+                return alias
+    # any embedding-like tensor (tied layouts, incl. transformer.wte.weight)
+    for n in names:
+        if n.endswith(("embed_tokens.weight", "word_embeddings.weight", "wte.weight")):
+            return n
+    return None
+
+
+def largest_2d(names, shapes):
+    best, best_elems = None, 0
+    for n in names:
+        s = shapes.get(n)
+        if s is not None and len(s) == 2:
+            elems = int(s[0]) * int(s[1])
+            if elems > best_elems:
+                best, best_elems = n, elems
+    return best
+
+
+def _hf_config(model_id):
+    try:
+        return http_get_json(f"https://huggingface.co/{model_id}/resolve/main/config.json", timeout=30)
+    except Exception:
+        return None
+
+
+def _hf_license(model_id):
+    for url in (f"https://huggingface.co/{model_id}/resolve/main/LICENSE", f"https://huggingface.co/{model_id}/raw/main/LICENSE"):
+        try:
+            req = urllib.request.Request(url, headers=_hf_auth_headers(url))
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                text = resp.read(2000).decode("utf-8", "replace").strip()
+                if len(text) > 10:
+                    return text[:200]
+        except Exception:
+            continue
+    return None
+
+
+def _hf_model_index(model_id, rev="main"):
+    try:
+        return http_get_json(f"https://huggingface.co/{model_id}/resolve/{rev}/model.safetensors.index.json", timeout=20)
+    except Exception:
+        return None
+
+
+def _normalize_hf_repo(s):
+    if not s or not s.strip():
+        return None
+    s = s.strip().rstrip("/")
+    if s.startswith(("http://", "https://")):
+        try:
+            parts = urlparse(s).path.strip("/").split("/")
+            if len(parts) >= 2 and parts[0] and parts[1]:
+                return f"{parts[0]}/{parts[1]}"
+        except Exception:
+            return None
+        return None
+    s = s.split("@")[0].split(":")[0].strip()
+    parts = s.split("/")
+    if len(parts) >= 2 and parts[0] and parts[1]:
+        return f"{parts[0]}/{parts[1]}"
+    return None
+
+
+def _base_paths(base_id):
+    norm = _normalize_hf_repo(base_id)
+    if norm is None:
+        return None
+    org, model = (x.lower() for x in norm.split("/"))
+    file_path = ctx.VOICES_DIR / "base" / org / f"{model}.safetensors"
+    return file_path, ctx.VOICES_DIR / "base" / org / f"{model}.json"
+
+
+def _hf_api_base_model(source_id):
+    try:
+        data = http_get_json(f"https://huggingface.co/api/models/{source_id}", timeout=15)
+        card = data.get("cardData") or {}
+        bm = card.get("base_model") or data.get("base_model")
+        if bm is None:
+            return None
+        if isinstance(bm, str):
+            return [bm]
+        if isinstance(bm, list):
+            return [x for x in bm if isinstance(x, str) and x.strip()]
+    except Exception:
+        return None
+    return None
+
+
+def _hf_mergekit_base(source_id):
+    for tmpl in (
+        f"https://huggingface.co/{source_id}/raw/main/mergekit_config.yml",
+        f"https://huggingface.co/{source_id}/raw/main/mergekit_config.yaml",
+    ):
+        try:
+            req = urllib.request.Request(tmpl, headers=_hf_auth_headers(tmpl))
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                text = resp.read().decode("utf-8", "replace")
+            for line in text.splitlines():
+                line = line.strip()
+                if line.startswith("#"):
+                    continue
+                m = re.search(r'base_model\s*:\s*["\']?\s*([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)', line)
+                if m:
+                    return m.group(1).strip()
+        except Exception:
+            continue
+    return None
+
+
+def _detect_base(source_id):
+    raw = _hf_api_base_model(source_id)
+    if not raw:
+        return None, False, 0, []
+    if len(raw) == 1:
+        return raw[0], False, 1, raw
+    tried = _hf_mergekit_base(source_id)
+    if tried:
+        return tried, True, len(raw), raw
+    return raw[0], True, len(raw), raw
+
+
+class TensorRef:
+    __slots__ = ("name", "dtype", "shape")
+
+    def __init__(self, name, dtype, shape):
+        self.name = name
+        self.dtype = dtype
+        self.shape = tuple(int(x) for x in shape)
+
+    def __repr__(self):
+        return f"TensorRef({self.name!r}, {self.dtype}, {self.shape})"
+
+
+class SafetensorsSource:
+    kind = "safetensors"
+
+    def __init__(self, path=None, repo=None, url=None, rev=None):
+        self.path = str(path) if path else None
+        self.repo = repo
+        self.url = url
+        self.rev = rev or "main"
+        self._header = None
+        self._header_size = None
+        self._index = None            # weight_map for sharded repos
+        self._shard_headers = {}      # shard file -> (header_size, tensors)
+
+    def _local(self):
+        """(header_size, tensors) for a local file — read once, then cached."""
+        if self.path and self._header_size is None:
+            with open(self.path, "rb") as f:
+                self._header_size = struct.unpack("<Q", f.read(8))[0]
+                self._header = json.loads(f.read(self._header_size))
+        return self._header_size, {k: v for k, v in self._header.items() if k != "__metadata__"}
+
+    def _single_url(self):
+        if self.url:
+            return self.url
+        return f"https://huggingface.co/{self.repo}/resolve/{self.rev}/model.safetensors"
+
+    def _load_index(self):
+        if self._index is not None or self.path or self.url:
+            return
+        idx = _hf_model_index(self.repo, self.rev)
+        self._index = idx.get("weight_map") if idx else None
+
+    def names(self):
+        if self.path:
+            return list(self._local()[1].keys())
+        if self.repo and self.url is None:
+            self._load_index()
+            if self._index is not None:
+                return list(self._index.keys())
+        # single remote file
+        self._load_single_header()
+        return list(self._tensors().keys())
+
+    def _load_single_header(self):
+        if self._header is not None:
+            return
+        raw, _st, _e = http_range(self._single_url(), 0, 7)
+        self._header_size = struct.unpack("<Q", raw)[0]
+        raw, _st, _e = http_range(self._single_url(), 8, 8 + self._header_size - 1)
+        self._header = json.loads(raw)
+
+    def _tensors(self):
+        return {k: v for k, v in self._header.items() if k != "__metadata__"}
+
+    def _shard_info(self, name):
+        """Return (url, header_size, tensors) for the shard containing `name`."""
+        if self.path:
+            hs, tensors = self._local()
+            return None, hs, tensors
+        if self.url:
+            self._load_single_header()
+            return self._single_url(), self._header_size, self._tensors()
+        # repo
+        self._load_index()
+        if self._index is None:
+            self._load_single_header()
+            return self._single_url(), self._header_size, self._tensors()
+        shard = self._index.get(name)
+        if shard is None:
+            raise KeyError(name)
+        if shard not in self._shard_headers:
+            url = f"https://huggingface.co/{self.repo}/resolve/{self.rev}/{shard}"
+            raw, _st, _e = http_range(url, 0, 7)
+            hs = struct.unpack("<Q", raw)[0]
+            raw, _st, _e = http_range(url, 8, 8 + hs - 1)
+            tensors = {k: v for k, v in json.loads(raw).items() if k != "__metadata__"}
+            self._shard_headers[shard] = (url, hs, tensors)
+        return self._shard_headers[shard]
+
+    def ref(self, name):
+        if self.path:
+            info = self._local()[1][name]
+            return TensorRef(name, info["dtype"], info["shape"])
+        url, hs, tensors = self._shard_info(name)
+        info = tensors[name]
+        return TensorRef(name, info["dtype"], info["shape"])
+
+    def read_raw(self, name):
+        if self.path:
+            hs, tensors = self._local()
+            info = tensors[name]
+            begin, end = info["data_offsets"]
+            with open(self.path, "rb") as f:
+                f.seek(8 + hs + begin)
+                return f.read(end - begin)
+        url, hs, tensors = self._shard_info(name)
+        info = tensors[name]
+        begin, end = info["data_offsets"]
+        data, _st, _e = http_range(url, 8 + hs + begin, 8 + hs + end - 1, timeout=300)
+        return data
+
+    def read_raw_slice(self, name, byte_off, byte_len):
+        """Minimal slice read: byte_off/byte_len relative to the tensor's data."""
+        if self.path:
+            hs, tensors = self._local()
+            info = tensors[name]
+            begin = info["data_offsets"][0] + byte_off
+            with open(self.path, "rb") as f:
+                f.seek(8 + hs + begin)
+                return f.read(byte_len)
+        url, hs, tensors = self._shard_info(name)
+        info = tensors[name]
+        begin = info["data_offsets"][0] + byte_off
+        data, _st, _e = http_range(url, 8 + hs + begin, 8 + hs + begin + byte_len - 1, timeout=300)
+        return data
+
+    def read_f32(self, name):
+        info = self.ref(name)
+        return decode_to_f32(self.read_raw(name), info.dtype, info.shape)
+
+
+class GgufSource:
+    kind = "gguf"
+
+    def __init__(self, path=None, url=None, rev=None):
+        self.path = str(path) if path else None
+        self.url = url
+        self.rev = rev or "main"
+        self._reader = None
+        self._remote = None
+
+    def _load(self):
+        if self.path:
+            if self._reader is None:
+                from gguf import GGUFReader
+                self._reader = GGUFReader(self.path)
+        elif self._remote is None:
+            self._remote = _parse_gguf_header(self.url)
+
+    def names(self):
+        self._load()
+        if self._reader is not None:
+            return [t.name for t in self._reader.tensors]
+        return list(self._remote[2].keys())
+
+    def ref(self, name):
+        from gguf.constants import GGMLQuantizationType as Q
+        self._load()
+        if self._reader is not None:
+            for t in self._reader.tensors:
+                if t.name == name:
+                    return TensorRef(name, t.tensor_type.name, tuple(reversed(t.shape)))
+            raise KeyError(name)
+        dims, gtype, _off, _nbytes = self._remote[2][name]
+        return TensorRef(name, Q(gtype).name, tuple(reversed(dims)))
+
+    def read_f32(self, name):
+        from gguf.constants import GGMLQuantizationType as Q
+        self._load()
+        if self._reader is not None:
+            for t in self._reader.tensors:
+                if t.name == name:
+                    return _gguf_tensor_f32(t)
+            raise KeyError(name)
+        dims, gtype, data_offset, n_bytes = self._remote[2][name]
+        start = self._remote[1] + data_offset
+        raw, _st, _e = http_range(self.url, start, start + n_bytes - 1, timeout=300)
+        return _gguf_raw_to_f32(raw, Q(gtype), dims)
+
+    def read_raw(self, name):
+        """Exact tensor bytes in file order (any quant, incl. K/IQ blocks)."""
+        import numpy as np
+        if self.path:
+            self._load()
+            for t in self._reader.tensors:
+                if t.name == name:
+                    return t.data.tobytes() if t.data.dtype == np.uint8 else memoryview(t.data).cast("B").tobytes()
+            raise KeyError(name)
+        dims, gtype, data_offset, n_bytes = self._remote[2][name]
+        start = self._remote[1] + data_offset
+        raw, _st, _e = http_range(self.url, start, start + n_bytes - 1, timeout=300)
+        return raw
+
+    def read_raw_slice(self, name, byte_off, byte_len):
+        """Minimal slice read: byte_off/byte_len relative to the tensor's raw bytes."""
+        import numpy as np
+        if self.path:
+            self._load()
+            for t in self._reader.tensors:
+                if t.name == name:
+                    try:
+                        # flatten to bytes FIRST: bare mv[i:j] slices dim-0 rows, not bytes
+                        mv = memoryview(t.data).cast("B")
+                        return mv[byte_off:byte_off + byte_len].tobytes()
+                    except Exception:
+                        return self.read_raw(name)[byte_off:byte_off + byte_len]
+            raise KeyError(name)
+        dims, gtype, data_offset, n_bytes = self._remote[2][name]
+        start = self._remote[1] + data_offset + byte_off
+        raw, _st, _e = http_range(self.url, start, start + byte_len - 1, timeout=300)
+        return raw
+
+
+def open_source(arg, rev=None):
+    p = Path(arg).expanduser()
+    if p.exists():
+        if p.is_dir():
+            ggufs = sorted(p.glob("*.gguf"))
+            if ggufs:
+                return GgufSource(path=str(ggufs[0]))
+            if (p / "model.safetensors").exists():
+                return SafetensorsSource(path=str(p / "model.safetensors"))
+            _fail(f"  ✗ No model.safetensors or .gguf found in {arg}.")
+        if p.is_file():
+            return GgufSource(path=str(p)) if _is_gguf_file(str(p)) else SafetensorsSource(path=str(p))
+    if arg.startswith(("http://", "https://")):
+        if arg.rstrip("/").split("/")[-1].endswith(".gguf"):
+            return GgufSource(url=arg)
+        return SafetensorsSource(url=arg)
+    return _source_from_repo(arg.strip().rstrip("/"), rev=rev)
+
+
+def _source_from_repo(repo, rev=None):
+    rev = rev or "main"
+    try:
+        tree = http_get_json(f"https://huggingface.co/api/models/{repo}/tree/{rev}", timeout=20)
+        files = [f.get("path", "") for f in tree if f.get("path")]
+        ggufs = [f for f in files if f.endswith(".gguf")]
+        if ggufs:
+            chosen = _pick_gguf(ggufs)
+            if ctx.VERBOSE:
+                _note(f"GGUF repo — using {chosen}")
+            return GgufSource(url=f"https://huggingface.co/{repo}/resolve/{rev}/{chosen}", rev=rev)
+        if any(f.endswith(".safetensors") for f in files):
+            return SafetensorsSource(repo=repo, rev=rev)
+        if files:
+            _fail(f"  ✗ '{repo}' has no .safetensors or .gguf files (found: {', '.join(files[:6])}{'…' if len(files) > 6 else ''}).")
+    except SystemExit:
+        raise
+    except Exception:
+        pass
+    return SafetensorsSource(repo=repo, rev=rev)
+
+
+def _pick_gguf(files):
+    files = sorted(files)
+    for key in ("fp16", "f16", "q8_0"):
+        for f in files:
+            if key in f.lower():
+                return f
+    return files[0]
+
+
+def _sanitize_voice_name(name):
+    if not name or not name.strip():
+        return None
+    name = name.strip()
+    if name.lower().startswith("delta-") or name in (".", ".."):
+        return None
+    bad = set("/\\.: ")
+    for c in name:
+        if c in bad or ord(c) < 32:
+            return None
+    return name
+
+
+_NAME_RULES = "Use letters, numbers, hyphens, underscores (no spaces, /, \\, dots, colons; not starting with delta-)."
+
+
+def _public_source(ref):
+    """Share-safe form of a model reference for voice.json/reports.
+    HF ids pass through; URLs lose userinfo/query/fragment; local paths
+    collapse to basename (directories leak usernames)."""
+    s = (ref or "").strip()
+    if not s or s == "—":
+        return s
+    try:
+        u = urlparse(s)
+        if u.scheme in ("http", "https"):
+            net = u.hostname or ""
+            if u.port:
+                net += f":{u.port}"
+            return f"{u.scheme}://{net}{u.path}"
+        if u.scheme == "file":
+            return Path(u.path).name or s
+    except Exception:
+        pass
+    if (s.startswith(("/", "~", ".")) or "\\" in s or len(s) > 2 and s[1] == ":"
+            or Path(s).expanduser().exists()):
+        return Path(s).name or s
+    return s
+
+
+def _slugify_voice_name(raw, fallback="voice"):
+    """Derive a valid voice name from arbitrary input (filenames, model IDs).
+    Lowercases, maps runs of invalid chars to '-', collapses, trims to 64 chars."""
+    s = str(raw or "").strip().lower()
+    if not s:
+        return fallback
+    s = re.sub(r"[^a-z0-9_-]+", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-_")[:64]
+    return s or fallback

vlib/tensors.py

@@ -0,0 +1,488 @@
+"""Tensor file-format primitives: safetensors, GGUF headers, dtype math, quant predicates."""
+
+from pathlib import Path
+import json
+import os
+import struct
+import urllib.error
+import urllib.request
+from vlib.ui import _fail
+from vlib.net import _hf_auth_headers
+
+
+def _validate_safetensors_header(header, file_size, header_size):
+    """Validate data_offsets are sane. Raises ValueError on corruption."""
+    tensors = {k: v for k, v in header.items() if k != "__metadata__"}
+    data_len = file_size - 8 - header_size
+    if data_len < 0:
+        raise ValueError(f"header {header_size} exceeds file {file_size}")
+    # collect and validate offsets
+    intervals = []
+    for name, info in tensors.items():
+        if not isinstance(info.get("data_offsets"), (list, tuple)) or len(info["data_offsets"]) != 2:
+            raise ValueError(f"tensor {name!r} missing data_offsets")
+        begin, end = info["data_offsets"]
+        if not isinstance(begin, int) or not isinstance(end, int) or begin < 0 or end < begin or end > data_len:
+            raise ValueError(f"tensor {name!r} offsets [{begin},{end}) out of bounds (data_len {data_len})")
+        shape = info.get("shape")
+        dtype = info.get("dtype")
+        if dtype is not None:
+            try:
+                bpe = dtype_bytes(dtype)
+            except ValueError:
+                raise ValueError(f"tensor {name!r} unknown dtype {dtype!r}")
+            if isinstance(shape, (list, tuple)):
+                prod = 1
+                for d in shape:
+                    prod *= int(d)
+                expected = prod * bpe
+                if expected != (end - begin):
+                    raise ValueError(f"tensor {name!r} shape {shape} dtype {dtype} expects {expected} bytes, got {end-begin}")
+        intervals.append((begin, end, name))
+    intervals.sort()
+    for i in range(1, len(intervals)):
+        if intervals[i][0] < intervals[i-1][1]:
+            raise ValueError(f"overlapping offsets: {intervals[i-1][2]!r} and {intervals[i][2]!r}")
+
+
+def read_safetensors(path):
+    try:
+        file_size = os.path.getsize(path)
+        with open(path, "rb") as f:
+            raw = f.read(8)
+            if len(raw) < 8:
+                raise ValueError("file too short")
+            header_size = struct.unpack("<Q", raw)[0]
+            if header_size <= 0 or header_size + 8 > file_size:
+                raise ValueError(f"header_size {header_size} not sane for {file_size} bytes")
+            header = json.loads(f.read(header_size))
+            _validate_safetensors_header(header, file_size, header_size)
+    except (json.JSONDecodeError, ValueError, OSError, struct.error) as exc:
+        raise ValueError(f"{path} is not a valid .safetensors file.") from exc
+    return header, {k: v for k, v in header.items() if k != "__metadata__"}
+
+
+def write_safetensors(tensors, out_path):
+    header, offset = {}, 0
+    for name, (data, dtype, shape) in tensors.items():
+        n = len(data)
+        header[name] = {"dtype": dtype, "shape": list(shape), "data_offsets": [offset, offset + n]}
+        offset += n
+    hj = json.dumps(header).encode("utf-8")
+    # atomic write via tmp + fsync
+    tmp_path = str(out_path) + ".tmp"
+    with open(tmp_path, "wb") as f:
+        f.write(struct.pack("<Q", len(hj)))
+        f.write(hj)
+        for name in tensors:
+            f.write(tensors[name][0])
+        f.flush()
+        try:
+            os.fsync(f.fileno())
+        except Exception:
+            pass
+    os.replace(tmp_path, str(out_path))
+    try:
+        # fsync parent dir for durability
+        dirfd = os.open(os.path.dirname(os.path.abspath(str(out_path))) or ".", os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+    return os.path.getsize(out_path)
+
+
+def _write_safetensors_streaming(tensor_name, src_path, src_total, dtype, shape, out_path):
+    header = {tensor_name: {"dtype": dtype, "shape": list(shape), "data_offsets": [0, src_total]}}
+    hj = json.dumps(header).encode("utf-8")
+    with open(out_path, "wb") as out, open(src_path, "rb") as inp:
+        out.write(struct.pack("<Q", len(hj)))
+        out.write(hj)
+        while True:
+            b = inp.read(8 << 20)
+            if not b:
+                break
+            out.write(b)
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+
+
+def rewrite_safetensors_tensor(target_path, out_path, replace_name, replace_bytes, replace_dtype, replace_shape):
+    """Copy target_path -> out_path, replacing one tensor's bytes. The tensor's
+    dtype/shape may change but its byte size must stay identical (offsets fixed)."""
+    with open(target_path, "rb") as f:
+        header_size = struct.unpack("<Q", f.read(8))[0]
+        raw_hdr = f.read(header_size)
+        if len(raw_hdr) != header_size:
+            _fail(f"  ✗ Truncated header in {target_path}.")
+        header = json.loads(raw_hdr)
+        _validate_safetensors_header(header, os.path.getsize(target_path), header_size)
+    tensors = {k: v for k, v in header.items() if k != "__metadata__"}
+    if replace_name not in tensors:
+        _fail(f"  ✗ Tensor '{replace_name}' not found in {target_path}.")
+    old_n = tensors[replace_name]["data_offsets"][1] - tensors[replace_name]["data_offsets"][0]
+    if len(replace_bytes) != old_n:
+        _fail(f"  ✗ Byte-size mismatch replacing '{replace_name}' ({len(replace_bytes)} vs {old_n}).")
+    new_header = dict(header)
+    offset = 0
+    for name in header:
+        if name == "__metadata__":
+            continue
+        if name == replace_name:
+            new_header[name] = {"dtype": replace_dtype, "shape": list(replace_shape), "data_offsets": [offset, offset + len(replace_bytes)]}
+        else:
+            n = tensors[name]["data_offsets"][1] - tensors[name]["data_offsets"][0]
+            new_header[name] = {"dtype": tensors[name]["dtype"], "shape": tensors[name]["shape"], "data_offsets": [offset, offset + n]}
+        offset += new_header[name]["data_offsets"][1] - new_header[name]["data_offsets"][0]
+    hj = json.dumps(new_header).encode("utf-8")
+    data_start = 8 + header_size
+    with open(target_path, "rb") as src, open(out_path, "wb") as out:
+        out.write(struct.pack("<Q", len(hj)))
+        out.write(hj)
+        for name in header:
+            if name == "__metadata__":
+                continue
+            begin, end = tensors[name]["data_offsets"]
+            if name == replace_name:
+                out.write(replace_bytes)
+                src.seek(data_start + end)
+            else:
+                src.seek(data_start + begin)
+                remaining = end - begin
+                while remaining:
+                    b = src.read(min(8 << 20, remaining))
+                    if not b:
+                        _fail(f"  ✗ Truncated read for tensor '{name}' in {target_path} (missing {remaining} bytes).")
+                    out.write(b)
+                    remaining -= len(b)
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+
+
+def _safetensors_write_repl(target_path, repl, out_path):
+    """Single-pass safetensors rewrite. repl maps tensor name -> (bytes, dtype, shape).
+    Streams the target once: replacement bytes spliced in, unchanged bytes pass through.
+    Atomic via tmp+fsync+replace. Same per-tensor guards as rewrite_safetensors_tensor."""
+    with open(target_path, "rb") as f:
+        header_size = struct.unpack("<Q", f.read(8))[0]
+        raw_hdr = f.read(header_size)
+        if len(raw_hdr) != header_size:
+            _fail(f"  ✗ Truncated header in {target_path}.")
+        header = json.loads(raw_hdr)
+        _validate_safetensors_header(header, os.path.getsize(target_path), header_size)
+    tensors = {k: v for k, v in header.items() if k != "__metadata__"}
+    for name in repl:
+        if name not in tensors:
+            _fail(f"  ✗ Tensor '{name}' not found in {target_path}.")
+        old_n = tensors[name]["data_offsets"][1] - tensors[name]["data_offsets"][0]
+        if len(repl[name][0]) != old_n:
+            _fail(f"  ✗ Byte-size mismatch replacing '{name}' ({len(repl[name][0])} vs {old_n}).")
+    new_header = dict(header)
+    offset = 0
+    for name in header:
+        if name == "__metadata__":
+            continue
+        if name in repl:
+            _rb, _rd, _rs = repl[name]
+            new_header[name] = {"dtype": _rd, "shape": list(_rs), "data_offsets": [offset, offset + len(_rb)]}
+        else:
+            n = tensors[name]["data_offsets"][1] - tensors[name]["data_offsets"][0]
+            new_header[name] = {"dtype": tensors[name]["dtype"], "shape": tensors[name]["shape"], "data_offsets": [offset, offset + n]}
+        offset += new_header[name]["data_offsets"][1] - new_header[name]["data_offsets"][0]
+    hj = json.dumps(new_header).encode("utf-8")
+    data_start = 8 + header_size
+    tmp_path = str(out_path) + ".tmp"
+    with open(target_path, "rb") as src, open(tmp_path, "wb") as out:
+        out.write(struct.pack("<Q", len(hj)))
+        out.write(hj)
+        for name in header:
+            if name == "__metadata__":
+                continue
+            begin, end = tensors[name]["data_offsets"]
+            if name in repl:
+                out.write(repl[name][0])
+                src.seek(data_start + end)
+            else:
+                src.seek(data_start + begin)
+                remaining = end - begin
+                while remaining:
+                    b = src.read(min(8 << 20, remaining))
+                    if not b:
+                        _fail(f"  ✗ Truncated read for tensor '{name}' in {target_path} (missing {remaining} bytes).")
+                    out.write(b)
+                    remaining -= len(b)
+        out.flush()
+        try:
+            os.fsync(out.fileno())
+        except Exception:
+            pass
+    os.replace(tmp_path, str(out_path))
+
+
+_DTYPE_BYTES_MAP = {
+    "F32": 4, "FP32": 4, "F64": 8,
+    "F16": 2, "FP16": 2, "BF16": 2, "BF16E8M": 2, "F16E5M6": 2,
+    "I8": 1, "U8": 1, "BOOL": 1, "I16": 2, "I32": 4, "I64": 8,
+}
+
+
+def dtype_bytes(dtype):
+    try:
+        return _DTYPE_BYTES_MAP[dtype.upper()]
+    except KeyError:
+        raise ValueError(f"unsupported dtype {dtype}")
+
+
+def bf16_to_f32(u16):
+    import numpy as np
+    return (u16.astype(np.uint32) << 16).view(np.float32).copy()
+
+
+def decode_to_f32(raw, dtype, shape):
+    import numpy as np
+    d = dtype.upper()
+    # length sanity: prevent silent truncation or over-read
+    try:
+        bpe = dtype_bytes(d)
+    except ValueError:
+        raise
+    prod = 1
+    for dim in shape:
+        prod *= int(dim)
+    expected = prod * bpe
+    if len(raw) != expected:
+        raise ValueError(f"decode length mismatch for {dtype} {shape}: got {len(raw)} bytes, expected {expected}")
+    if d in ("BF16", "BF16E8M"):
+        return bf16_to_f32(np.frombuffer(raw, dtype=np.uint16)).reshape(shape)
+    if d in ("F16", "FP16", "F16E5M6"):
+        return np.frombuffer(raw, dtype=np.float16).reshape(shape).astype(np.float32)
+    if d in ("F32", "FP32"):
+        return np.frombuffer(raw, dtype=np.float32).reshape(shape).astype(np.float32)
+    raise ValueError(f"unsupported dtype {dtype}")
+
+
+def encode_from_f32(arr, dtype):
+    import numpy as np
+    d = dtype.upper()
+    if d in ("F32", "FP32"):
+        return arr.astype(np.float32).tobytes()
+    if d in ("F16", "FP16", "F16E5M6"):
+        return arr.astype(np.float16).tobytes()
+    if d in ("BF16", "BF16E8M"):
+        u32 = arr.astype(np.float32).view(np.uint32)
+        # round-to-nearest-even (not truncation): matches standard BF16 cast
+        rounded = (u32 + 0x7FFF + ((u32 >> 16) & 1)) >> 16
+        return rounded.astype(np.uint16).tobytes()
+    raise ValueError(f"unsupported dtype {dtype}")
+
+
+def _gguf_tensor_f32(t):
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import dequantize
+    if t.tensor_type == Q.F32:
+        return np.ascontiguousarray(t.data, dtype=np.float32)
+    if t.tensor_type == Q.F16:
+        return t.data.astype(np.float32)
+    return dequantize(t.data, t.tensor_type)
+
+
+def _gguf_raw_to_f32(raw, ggml_type, dims):
+    import numpy as np
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import dequantize, quant_shape_to_byte_shape
+    rshape = tuple(reversed(dims))
+    if ggml_type == Q.F32:
+        return np.frombuffer(raw, dtype=np.float32).reshape(rshape).astype(np.float32)
+    if ggml_type == Q.F16:
+        return np.frombuffer(raw, dtype=np.float16).reshape(rshape).astype(np.float32)
+    return dequantize(np.frombuffer(raw, dtype=np.uint8).reshape(quant_shape_to_byte_shape(rshape, ggml_type)), ggml_type)
+
+
+def _gguf_raw_slice_to_f32(raw, ggml_type, off, n):
+    """Dequantize one element slice [off, off+n) of a quant tensor's raw bytes.
+    Expands to block alignment (blocks decode independently), dequantizes only the
+    covering blocks, then cuts the exact slice. Peak F32 is O(chunk), not O(tensor)."""
+    import numpy as np
+    from gguf.constants import GGML_QUANT_SIZES
+    from gguf.quants import dequantize
+    block_size, type_size = GGML_QUANT_SIZES[ggml_type]
+    u8 = np.frombuffer(raw, dtype=np.uint8)
+    b0 = off // block_size
+    b1 = (off + n + block_size - 1) // block_size
+    f32 = dequantize(u8[b0 * type_size:b1 * type_size].reshape(-1, type_size), ggml_type).reshape(-1)
+    return f32[off - b0 * block_size:off - b0 * block_size + n].astype(np.float32)
+
+
+_DELTA_CHUNK_ELEMS = 1 << 20  # 1M-elem (~4MB F32) streaming seam for delta math; mirrors the fast path
+
+
+def _gguf_nbytes(dims, ggml_type):
+    from gguf.constants import GGML_QUANT_SIZES
+    n = 1
+    for d in dims:
+        n *= int(d)
+    block_size, type_size = GGML_QUANT_SIZES[ggml_type]
+    return n * type_size // block_size
+
+
+def _parse_gguf_header(url):
+    """Fetch a remote GGUF's metadata + tensor table.
+    Returns (arch, header_size, {name: (dims, ggml_type, data_offset, n_bytes)}),
+    where header_size is the aligned offset of the data section."""
+    from gguf.constants import GGMLQuantizationType as Q
+    buf, base = b"", 0
+
+    def need(n):
+        nonlocal buf, base
+        while len(buf) < n:
+            a = base + len(buf)
+            b = a + max(n - len(buf), 256 * 1024) - 1
+            req = urllib.request.Request(url, headers=_hf_auth_headers(url, {"Range": f"bytes={a}-{b}"}))
+            with urllib.request.urlopen(req, timeout=120) as r:
+                chunk = r.read()
+            if not chunk:
+                break
+            buf += chunk
+
+    def take(n):
+        nonlocal buf, base
+        need(n)
+        out, buf, base = buf[:n], buf[n:], base + n
+        return out
+
+    u32 = lambda: struct.unpack("<I", take(4))[0]
+    u64 = lambda: struct.unpack("<Q", take(8))[0]
+    string = lambda: take(u64()).decode("utf-8", "replace")
+    sizes = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}
+
+    def skip_value(t):
+        if t == 8:
+            take(u64()); return
+        if t == 9:
+            et = u32(); n = u64()
+            if et not in sizes and et != 8:
+                raise ValueError(f"unknown GGUF array element type {et}")
+            if et == 8:
+                for _ in range(n):
+                    take(u64())
+            else:
+                take(n * sizes[et])
+            return
+        if t not in sizes:
+            raise ValueError(f"unknown GGUF value type {t}")
+        take(sizes[t])
+
+    if u32() != 0x46554747:
+        raise ValueError("not a GGUF file")
+    u32()  # version
+    tensor_count = u64()
+    kv_count = u64()
+    arch = None
+    alignment = 32
+    for _ in range(kv_count):
+        key = string()
+        t = u32()
+        if key == "general.architecture" and t == 8:
+            arch = take(u64()).decode("utf-8", "replace")
+        elif key == "general.alignment" and t == 4:
+            alignment = max(1, u32())
+        else:
+            skip_value(t)
+    tensors = {}
+    for _ in range(tensor_count):
+        name = string()
+        nd = u32()
+        dims = [u64() for _ in range(nd)]
+        gtype = u32()
+        data_offset = u64()
+        tensors[name] = (dims, Q(gtype), data_offset, _gguf_nbytes(dims, Q(gtype)))
+    # Tensor data_offsets are relative to the data section, which starts after
+    # the header (+ tensor infos), padded up to `general.alignment`.
+    header_size = base + ((-base) % alignment)
+    return arch, header_size, tensors
+
+
+def _is_gguf_file(path):
+    try:
+        with open(path, "rb") as f:
+            data = f.read(4)
+            return len(data) == 4 and data == b"GGUF"
+    except Exception:
+        return False
+
+
+_QUANT_DTYPES = frozenset()
+
+
+try:
+    from gguf.constants import GGMLQuantizationType as _QALL
+    _QUANT_DTYPES = frozenset(t.name for t in _QALL) - {"F32", "F16", "F64", "BF16",
+        "I8", "I16", "I32", "I64"}
+except Exception:
+    _QUANT_DTYPES = frozenset({"Q4_0", "Q4_1", "Q5_0", "Q5_1", "Q8_0", "Q8_1", "Q8_K", "Q1_0",
+        "Q2_K", "Q3_K", "Q3_K_XS", "Q3_K_S", "Q3_K_M", "Q3_K_L",
+        "Q4_K", "Q4_K_S", "Q4_K_M", "Q5_K", "Q5_K_M", "Q6_K", "Q8_K",
+        "IQ1_S", "IQ1_M", "IQ2_XXS", "IQ2_XS", "IQ2_S", "IQ3_XXS", "IQ3_S", "IQ4_XS", "IQ4_NL",
+        "TQ1_0", "TQ2_0", "MXFP4", "NVFP4"})
+
+
+def _is_ggml_quant(dtype):
+    return dtype.upper() in _QUANT_DTYPES
+
+
+def _is_quant_fetched(fetched):
+    return _is_ggml_quant(fetched[3])
+
+
+def _is_delta_safetensors(header_or_path):
+    """Check if file/header indicates delta via marker or metadata."""
+    try:
+        if isinstance(header_or_path, (str, Path)):
+            with open(header_or_path, "rb") as f:
+                hs = struct.unpack("<Q", f.read(8))[0]
+                hdr = json.loads(f.read(hs))
+        else:
+            hdr = header_or_path
+        if "delta.voice.marker" in hdr:
+            return True
+        meta = hdr.get("__metadata__")
+        if isinstance(meta, dict) and meta.get("type") == "delta":
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def _write_single_tensor_gguf(tensor_name, raw_path, n_bytes, ggml_type, shape, out_path):
+    """Write one tensor's exact raw quant blocks as a minimal standalone GGUF."""
+    from gguf import GGUFWriter
+    from gguf.constants import GGMLQuantizationType as Q
+    from gguf.quants import quant_shape_to_byte_shape
+    import numpy as np
+    qtype = Q[ggml_type]
+    # byte blocks are laid out in logical order (no reversal: the writer stores
+    # reversed file dims itself, and the reader exposes them back the same way)
+    byte_shape = quant_shape_to_byte_shape(tuple(int(x) for x in shape), qtype)
+    need = 1
+    for _d in byte_shape:
+        need *= _d
+    raw = np.fromfile(str(raw_path), dtype=np.uint8, count=need)
+    if raw.size != need:
+        _fail(f"  ✗ Short tensor data for '{tensor_name}' ({raw.size}/{need} bytes).")
+    tmp = str(out_path) + ".tmp"
+    writer = GGUFWriter(tmp, "voice", use_temp_file=False)
+    writer.add_tensor(tensor_name, raw.reshape(byte_shape), raw_dtype=qtype)
+    writer.write_header_to_file()
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file()
+    writer.close()
+    os.replace(tmp, str(out_path))

vlib/ui.py

@@ -0,0 +1,97 @@
+"""Terminal output, prompts, and formatting."""
+
+import os
+import sys
+
+
+_PLAIN_MAP = {"✓": "[OK]", "✗": "[ERR]", "⚠": "[WARN]", "→": ">", "↳": "->", "·": "-", "…": "...", "─": "-", "—": "-", "←": "<-", "↔": "<->"}
+
+
+def _plain():
+    return os.environ.get("VOICE_PLAIN") == "1"
+
+
+def _transform(msg):
+    if not _plain():
+        return msg
+    for k, v in _PLAIN_MAP.items():
+        msg = msg.replace(k, v)
+    return msg
+
+
+def _now_iso():
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _say(msg):
+    print(_transform(msg), flush=True)
+
+
+def _ok(msg):
+    _say(f"  ✓ {msg}")
+
+
+def _warn(msg):
+    _say(f"  ⚠ {msg}")
+
+
+def _step(msg):
+    _say(f"  → {msg}")
+
+
+def _note(msg):
+    _say(f"  ↳ {msg}")
+
+
+def _fail(msg):
+    sys.stdout.flush()
+    msg = str(msg).lstrip()
+    if msg.startswith("✗"):
+        msg = msg[1:].lstrip()
+    _say(f"  ✗ {msg}")
+    sys.exit(1)
+
+
+def _noninteractive(args):
+    if getattr(args, "non_interactive", False) or getattr(args, "yes", False):
+        return True
+    try:
+        return not sys.stdin.isatty()
+    except Exception:
+        return True
+
+
+def _progress_pref():
+    if _plain() or os.environ.get("REDUCE_MOTION") == "1":
+        return True
+    try:
+        return not sys.stdout.isatty()
+    except Exception:
+        return True
+
+
+def _confirm(question, args):
+    if getattr(args, "yes", False):
+        return True
+    if _noninteractive(args):
+        return False
+    try:
+        ans = input(question).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        _say("  ⚠ Cancelled.")
+        sys.exit(0)
+    return ans in ("y", "yes")
+
+
+def _trunc(s, w):
+    s = str(s)
+    return s[: w - 1] + "…" if len(s) > w else s
+
+
+def _term_width():
+    try:
+        import shutil
+        return shutil.get_terminal_size().columns
+    except Exception:
+        return 80

voice-cli.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b49d8f2c7bed7be28fa5c650fe9f0f892641bb1fa35236cb524aa4b760162a7a
+size 66864

voice.pyz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2148e2de112c40fe5eaaf2ad880c72e4ac925775fc3d6f51dbd8d6d36da7a103
+size 245086