## [1.3.1] - 2026-08-20

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.3.1] - 2026-08-20

### Changed
- Standardized AutoRound int4 tier progression to position `Compact` (33%) as the top tier in automated batch runs (`02_BF16-GGUF-to-ASHQ1.py` and `ASHQ1.py --tier all`).
- Configured `INT4_MODULE_PROFILES` to target `compact` for MTP and dspark modules on AutoRound int4 lineage checkpoints.
- Introduced `ASHQ1_INCLUDE_QUALITY=1` environment variable override for selective evaluation of the 36% Quality tier on int4 lineage models.

### Removed
- Retired default generation of the `Quality` tier on AutoRound int4 lineage, reflecting empirical validation across 1B to 9B models where perplexity improvement over `Compact` (33%) remains negligible (+0.0358 PPL on 9B, below 0.04 across all tested scales).

02_BF16-GGUF-to-ASHQ1.py

@@ -1,15 +1,15 @@
 #!/usr/bin/env python3
 r"""02_BF16-GGUF-to-ASHQ1.py — Automated ASHQ1 orchestrator.
 
-Execution order: modules (mmproj, MTP…) → tiers Mini → Quality → Nano.
-On AutoRound int4 lineage (provenance), Fidelity is skipped by default —
-information ceiling reached at Quality — and modules use Quality
-(override: ASHQ1_INCLUDE_FIDELITY=1).
+Execution order: modules (mmproj, MTP…) → tiers Mini → Compact → Nano.
+On AutoRound int4 lineage (provenance), Fidelity and Quality are skipped by default —
+information ceiling reached at Compact (negligible perplexity delta from 1B to 9B) —
+and modules use Compact (overrides: ASHQ1_INCLUDE_QUALITY=1, ASHQ1_INCLUDE_FIDELITY=1).
 The COMPLETE model (including MTP head) is preferred over the no-mtp trunk:
 ASHQ1 keeps the nextn layer at Q8_0 (Q6_K on int4 lineage) and excludes it from the size budget.
 Final naming: model-AutoRound-ASHQ1-Compact-33pc.gguf (AutoRound lineage detected
 via step 00 sidecar), model-ASHQ1-…-NNpc.gguf otherwise; mmproj-ASHQ1-Balanced-NNpc.gguf
-(pct relative to source mmproj). On int4 lineage Quality targets 36% instead of 39%.
+(pct relative to source mmproj).
 Lineage override: ASHQ1_LINEAGE=autoround|plain.
 """
 import os,re,sys,subprocess
@@ -23,7 +23,7 @@ MAIN_TIERS=["mini","compact","quality","fidelity"]
 # Longest running and least used: executed last
 LAST_TIER="nano"
 MODULE_PROFILES={"mtp":"fidelity","dspark":"fidelity"}
-INT4_MODULE_PROFILES={"mtp":"quality","dspark":"quality"}
+INT4_MODULE_PROFILES={"mtp":"compact","dspark":"compact"}
 
 def find_file_case_insensitive(directory,filename):
 	for f in os.listdir(directory):
@@ -178,10 +178,13 @@ def main():
 		print(f"  ℹ  {len(imatrix)} imatrix file(s) merged (max method): {', '.join(os.path.basename(p) for p in imatrix)}")
 
 	int4_lineage=int4_lineage_of(main_model) if has_main_model else False
-	if int4_lineage and os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1":
-		main_tiers=[t for t in MAIN_TIERS if t!="fidelity"]
+	if int4_lineage:
+		excluded=set()
+		if os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1":excluded.add("fidelity")
+		if os.environ.get("ASHQ1_INCLUDE_QUALITY")!="1":excluded.add("quality")
+		main_tiers=[t for t in MAIN_TIERS if t not in excluded]
 		module_profiles=INT4_MODULE_PROFILES
-		print("\n  ℹ  AutoRound int4 lineage detected — Fidelity skipped (information ceiling reached), modules set to Quality. Set ASHQ1_INCLUDE_FIDELITY=1 to override.")
+		print("\n  ℹ  AutoRound int4 lineage detected — Fidelity & Quality skipped (information ceiling reached at Compact), modules set to Compact. Overrides: ASHQ1_INCLUDE_QUALITY=1, ASHQ1_INCLUDE_FIDELITY=1.")
 	else:
 		main_tiers=MAIN_TIERS
 		module_profiles=MODULE_PROFILES

ASHQ1.py

@@ -1428,7 +1428,6 @@ def resolve_tier_ratio(tier,lineage):
 	return TIER_RATIOS[tier]
 
 ALL_RATIOS=dict(TIER_RATIOS)
-INT4_TIER_RATIOS={"quality":0.36}
 TIER_DISPLAY={"nano":"Nano"}
 
 def tier_label(tier:str)->str:
@@ -1575,9 +1574,12 @@ def tiers_main(args_list=None):
 			print(f"ERROR: Imatrix not found: {im}")
 			sys.exit(1)
 	tiers=["mini","compact","quality","fidelity","nano"] if args.tier=="all" else[args.tier]
-	if args.tier=="all" and int4_lineage_of(args.model) and os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1":
-		tiers.remove("fidelity")
-		print(f"  ℹ  AutoRound int4 lineage detected — Fidelity skipped (e₂ ≪ e₁ beyond {INT4_LINEAGE_CAP} on int4 classes). Set ASHQ1_INCLUDE_FIDELITY=1 to override.")
+	if args.tier=="all" and int4_lineage_of(args.model):
+		if os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1" and "fidelity" in tiers:
+			tiers.remove("fidelity")
+		if os.environ.get("ASHQ1_INCLUDE_QUALITY")!="1" and "quality" in tiers:
+			tiers.remove("quality")
+		print(f"  ℹ  AutoRound int4 lineage detected — Fidelity & Quality skipped (information ceiling reached at Compact). Overrides: ASHQ1_INCLUDE_QUALITY=1, ASHQ1_INCLUDE_FIDELITY=1.")
 	extra_args=[]
 	if args.allow_q3_or_lower:extra_args.append("--allow-q3-or-lower")
 	extra_args.extend(["--imatrix-method",args.imatrix_method,"--lineage",args.lineage])

CHARTER.md

@@ -52,8 +52,8 @@ When tied layers are detected (such as shared input/output embeddings or symmetr
 When weights are derived from an AutoRound W4A16 source (recorded via `.provenance.json` sidecars):
 * **Information Saturation**: Because the underlying weights have been pre-conditioned for 4-bit representations, assigning container formats above `Q5_K` yields negligible signal recovery ($\Delta \mathcal{Q} \to 0$).
 * **Automated Capping**: The ASHQ1 optimizer caps attention and FFN blocks at `Q5_K`, attention gates at `Q6_K`, and MTP heads at `Q6_K`, while recurrent memory states hold `Q8_0`. The bit-budget freed by these ceilings flows to the imatrix-ranked tensors that convert it into measurable error reduction.
-* **Tier Pruning**: On AutoRound int4 lineage, generation of the 48% `Fidelity` tier is skipped by default, focusing compute resources on optimal `Quality` (36%), `Compact` (33%), `Mini` (27%), and `Nano` (24% in the 2026-08-20 validation run) variants.
-* **Cap Saturation**: On AutoRound int4 lineage, `Compact` (33%) drives every attention and FFN projection to the `Q5_K` cap. Measured on a 9B `qwen35` source (17 091 MiB BF16): `Compact` ships 33.06%, `Quality` ships 35.49% against a 36% target. Beyond `Compact`, the budget buys `token_embd` (+280 MiB), `output` (+121 MiB) and the layer-0 FFN pair (+15 MiB); blocks 1 through 31 stay identical across both tiers. `Quality` therefore retargets to 36% on this lineage; other lineages keep 39%.
+* **Tier Pruning**: On AutoRound int4 lineage, generation of both the 48% `Fidelity` and 36% `Quality` tiers is skipped by default, focusing compute resources on optimal `Compact` (33%), `Mini` (27%), and `Nano` (24% in the 2026-08-20 validation run) variants.
+* **Cap Saturation**: On AutoRound int4 lineage, `Compact` (33%) drives every attention and FFN projection to the `Q5_K` cap. Measured on a 9B `qwen35` source (17 091 MiB BF16): `Compact` ships 33.06%, `Quality` ships 35.49% against a 36% target. Beyond `Compact`, the perplexity difference remains negligible across all model sizes (1B to 9B, with Δ PPL ≤ 0.0358 on 9B), as blocks 1 through 31 remain identical between tiers. `Compact` therefore represents the maximum standard tier for this lineage.
 * **Discrete Ceiling**: Once every capped class saturates, the upgrade queue holds only large indivisible moves — `output` Q5_K→Q6_K at +129 MiB, `token_embd` Q6_K→Q8_0 at +235 MiB. Reachable footprints become discrete: on the reference 9B source, 35.49%, then 36.25%, then 37.62%. A target landing between two steps delivers the lower one, which the greedy scheduler reports as remaining slack.
 
 ---

README.md

@@ -70,9 +70,9 @@ All tiers maintain strict byte-budget percentages relative to the original unqua
 
 *Note: Models originating from an AutoRound int4 lineage cap their weight allocations at `Q5_K`, as theoretical information saturation is fully realized. Attention gates settle at `Q6_K` and recurrent states at `Q8_0` on that lineage, and every tensor missing from the imatrix keeps `IQ4_XS` or above.*
 
-> **Int4 lineage tier ladder**: `Compact` (33%) already drives every attention and FFN projection to the `Q5_K` cap. Budget beyond that point buys `token_embd` and `output` precision only, so `Quality` retargets to **36%** on this lineage and writes `-Quality-36pc.gguf`. `Fidelity` stays pruned.
+> **Int4 lineage tier ladder**: `Compact` (33%) already drives every attention and FFN projection to the `Q5_K` cap. Because the perplexity gain beyond `Compact` is near-zero across all model sizes (1B to 9B, with Δ PPL ≤ 0.0358), `Compact` serves as the top tier on this lineage. Both `Quality` and `Fidelity` are skipped by default.
 >
-> Measured on a 9B `qwen35` source (17 091 MiB BF16): Nano **24.02%**, Mini **27.01%**, Compact **33.06%**, Quality **35.49%**. `Quality` stops short of its nominal target because the surviving upgrades are indivisible blocks of 129 MiB and above.
+> Measured on a 9B `qwen35` source (17 091 MiB BF16): Nano **24.02%**, Mini **27.01%**, Compact **33.06%**.
 
 ### Perplexity Benchmarks (Ornith-1.5-9B)
 

USAGE.md

@@ -77,7 +77,7 @@ python 01_create-calibration-dataset-and-imatrix.py --cpu-only
 Run script `02` to orchestrate multi-tier quantization:
 
 ```bash
-# Quantize all standard tiers (Nano, Mini, Compact, Quality) + mmproj
+# Quantize all standard tiers (Nano, Mini, Compact on AutoRound int4; + Quality on plain BF16) + mmproj
 python 02_BF16-GGUF-to-ASHQ1.py
 ```
 
@@ -120,6 +120,7 @@ Configure runtime behavior via optional environment variables:
 | Variable | Values | Purpose |
 | :--- | :---: | :--- |
 | `ASHQ1_LINEAGE` | `auto`, `autoround`, `plain` | Overrides the file naming lineage tag. |
+| `ASHQ1_INCLUDE_QUALITY` | `1`, `0` | Forces generation of the 36% Quality tier on int4 lineage models. |
 | `ASHQ1_INCLUDE_FIDELITY` | `1`, `0` | Forces generation of the 48% Fidelity tier on int4 lineage models. |
 | `GGML_CUDA_ENABLE_UNIFIED_MEMORY` | `1`, `0` | Enables CUDA unified memory for large activation processing in `llama-imatrix`. |
 | `LLAMA_CPP_DIR` | `/path/to/llama.cpp` | Specifies custom path to `llama.cpp` binaries. |