Alberto-Codes / Alberto-Codes/vramfit

Persist the measured row width in the sensitivity map, so a published map plans on its own again

Open
#558 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.