aiter-config-shape

aiter config shape-collision standard

Tuned config CSVs in aiter/configs/ are not read one file at a time. At runtime aiter/jit/core.py::AITER_CONFIGS.get_config_file merges, per family, the canonical aiter/configs/<name>.csv plus every aiter/configs/model_configs/*<name>*.csv, and update_config_files de-duplicates that merge on a key derived from the matching untuned file's columns (+ cu_num/gfx/_tag). If two rows across the merged files share that key, the merge raises RuntimeError: Found N duplicate shape entries during merge of '<family>'.

Consequence: a per-model config you add can be perfectly fine alone yet collide with a different model's config once both are on main. Single-PR CI only merges your file with current main, so two PRs that each add the same shape to different model files both pass, then break main after both land (cross-PR / merge-skew hazard). Reviewers routinely forget this.

Follow this whenever you add "tuned configs for model Y", upload/merge config CSVs, or touch anything under aiter/configs/**.

The hard rules

1. A key is (untuned columns) + cu_num, plus gfx/_tag when those columns are present. Never hand-pick key columns — they come from the family's *_untuned_*.csv header, exactly as runtime derives them (update_config_files appends cu_num if absent, gfx only when a gfx column exists in the merge, and _tag only when a _tag column exists). Do not assume M,N,K alone: e.g. a8w8 also keys on q_dtype_w, bf16 on bias,dtype,outdtype,scaleAB,bpreshuffle, fmoe on the full token,model_dim,inter_dim,expert,topk,act_type,dtype,q_dtype_*,q_type, use_g1u1,doweight_stage1 (+ _tag).
2. Your file is merged with the canonical file AND every other model file of the same family. Before uploading, check the merge, not just your file in isolation. The family is decided by the substring in the filename (*<tuned_file_name>*), e.g. dsv4_bf16_tuned_gemm.csv joins the bf16_tuned_gemm family.
3. One shape, one row across the whole family. If the shape already exists (in the canonical file or another model's file), do not re-add it. If yours is genuinely faster, replace the existing row rather than adding a second.
4. Run the collision guard and make it pass before you push. (below)
5. Resolve, never suppress. Fix by removing the redundant row (keeping the lowest-us winner) — do not widen keys, rename shapes, or delete the guard.
6. gfx matters. Archs that share a cu_num (e.g. gfx950 vs gfx1250 both report 256) are only distinguishable by gfx. Keep the real gfx the tuner wrote; don't drop the column. Legacy files without gfx are backfilled from cu_num (256→gfx950, 80/304→gfx942) — do not rely on that for new archs.