Alberto-Codes / Alberto-Codes/vramfit
Persist the measured row width in the sensitivity map, so a published map plans on its own again
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- Avg merge
- 6h 8m
- Merged PRs (30d)
- 105
Description
## Gap
The scan measures every group's row width, discards it, and the plan
then needs the checkpoint to measure it again.
`refuse_straddling_rows(row_length, bits)`
(`src/vramfit/adapters/outbound/scan/kquant.py:402`) reads each
group's row length during the scan, to refuse a cell whose mapped
type cannot tile the rows (ADR-0018). The sensitivity-map schema
keeps no field for it, so the number is thrown away at the end of
the scan.
#515 then made that same width the authority for the 256
super-block decision. The plan reads it from the checkpoint's
safetensors headers, because the map does not carry it.
**The cost is a capability, not an inconvenience.** A published map
alone no longer plans under llama.cpp at `stack` or `tensor`
granularity. An operator with a published Qwen3-Coder-30B stack map
and no local checkpoint runs:
vramfit plan map.json --vram 24GiB --runtime llama.cpp
and is refused, for a map that already carries every damage
measurement. Before #515 that command solved.
Two records build on what ended:
- `docs/explanation/artifact-ecosystem.md:90` — "Publish maps for
models we did not pack. **The map is the product.**"
- the same page's phase 3 — "`vramfit plan` is torch-free pure
Python, so a Hugging Face Space can re-solve recipes live against
published maps". A Space has the map and no checkpoint.
ADR-0028's 2026-09-05 amendment records the consequence. This issue
carries the remedy.
## Ask
Decide whether the sensitivity map persists each group's measured
row width.
Persisting it would restore map-only planning, unblock the phase 3
Space, and make the map self-sufficient for the decision it now
drives — the routing would travel with the measurement that
justifies it, instead of requiring a checkpoint to re-derive a
number the scan already had.
Two parts need a ruling, which is why this is a decision:
1. **The schema.** A new per-group field bumps `vramfit_schema`,
which is 3 today (`MAP_SCHEMA_VERSION`,
`src/vramfit/adapters/outbound/sensitivity_map_json.py:77`).
2. **Older maps.** Every published map carries no width. Decide
whether such a map refuses under llama.cpp at `stack` or
`tensor` granularity, falls back to the checkpoint as today, or
is re-scanned. `MAP_SCHEMA_ALSO_READS` currently accepts 2, so
the reader already has a precedent for reading an older map.
A `layer`-granularity map needs no width and is unaffected either
way: a layer group holds several row widths and takes the ADR-0012
k-quant table.
## Origin
Found by the #515 review on 2026-09-05, as
`map-only-planning-ends-and-no-record-says-so`. Firstmate ruled the
same day that recording the consequence belongs in #515 and the
schema change does not.
Contributor guide
Research direction
Read the sensitivity-map schema and compatibility logic in src/vramfit/adapters/outbound/sensitivity_map_json.py, including MAP_SCHEMA_VERSION and MAP_SCHEMA_ALSO_READS, then trace the measured width from src/vramfit/adapters/outbound/scan/kquant.py:402 into planning. Review docs/explanation/artifact-ecosystem.md:90 and the ADR-0028 amendment. Done means the schema decision, versioning, and behavior for older maps are settled and recorded.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100