Beyond-KLE/journal/2026-09-21-idx-necessity.md

IDXレイヤーは必要か (schema P-1解消)

結論

必要。ただし「最も重要な抽象化層」「エコシステムで最も欠けている層」という位置づけは誤りで、 ドキュメントから落とす。

IDXの中身は「どのキーに、どの順で番号を振るか」という順列だけ。情報ではなく決めごとで、 PHYからもELCからも導出できない。導出できないから正本として置く。

あわせて2点決めた。

• MAPはキー番号ではなくPHYのキーIDを参照する
• IDXの保存形式は order: string[] (並びの位置が番号)

発端

ユーザーの指摘: 「PHYのidやELCの接続がそのままキー番号になってしまうのでは？ わざわざIDXを振る意味が薄れてきている」。

薄く見える原因は特定できた。IDXが持つと思われていたものが順次出ていったため。

元々IDXが持つとされたもの	現在の置き場	コミット
row / col	ELCの配線から出力時に導出	5bba75d
LEDの識別番号	ELC (チェーン順序)	eb96ff0

引き算の結果、キー番号との対応だけが残った。薄いという認識自体は正しい。

案の比較

案	キー番号の出どころ	判定
IDXが正本として持つ	設計者が決める並び順	採用
PHYのツリー順	幾何の編集順	reparentで番号が動きキーマップがずれる
ELCのマトリクス順	row/col	分割で並びが一致しない。欠番がある。再配線で動く
そもそも番号を持たない	(MAPがPHYのキーIDを参照)	公開インターフェースが固定できない

最後の案が一番惜しかった。row/colを出力時に割り当てる判断と揃えるなら、キー番号も Firmware Generatorが生成する派生情報にできそうに見える。しかし番号が再生成のたびに動くと、 公開した基板に対して他人が書いたキーマップが別のキーを指す。公開インターフェースは固定が要る。

結果として、MAPの参照だけをPHYのキーIDに移し、番号の並びはIDXに残す形にした。 番号がずれてもMAPは無傷で、番号は固定される。

根拠: 3つの処理系はどれもこの順列を手書きしている

• QMK: LAYOUT マクロの引数順 / keyboard.json の layouts.<NAME>.layout[] の配列順
• ZMK: matrix transform の map の並び順
• KMK: coord_mapping の並び順

QMK Configuratorの説明:

The Configurator's API uses the layout macro and the JSON file we've given it to create a visual representation of the keyboard that has each visual object tied to a specific key, in sequence. When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with KC_NUM as the first key, and so on as the keymap is built.

The names themselves actually don't matter, as long as they match between the top section, which receives the keycodes from the keymap, and the bottom half which designates where each key is in the matrix.

ZMKの matrix transform map:

It should have one item per logical position in the keymap. Each item should list the physical row and column that trigger the key in that position.

つまりIDXは「欠けている層」ではない。Cのマクロの引数順として存在していて、形式化されていないだけ。 引数の数え間違いでキーが1つずれるのが定番のバグであることも、この層が手書きである傍証になる。

出典:

• https://docs.qmk.fm/reference_configurator_support
• https://docs.qmk.fm/reference_info_json
• https://zmk.dev/docs/config/layout
• https://github.com/KMKfw/kmk_firmware/blob/main/docs/en/porting_to_kmk.md

根拠: マトリクス順 ≠ キー番号順 の実物

KMKのCorne向け coord_mapping。

coord_mapping = [
 0,  1,  2,  3,  4,  5,  24, 25, 26, 27, 28, 29,
 6,  7,  8,  9, 10, 11,  30, 31, 32, 33, 34, 35,
12, 13, 14, 15, 16, 17,  36, 37, 38, 39, 40, 41,
            21, 22, 23,  42, 43, 44,
]

配列の位置がキー番号、値がマトリクス上の通し番号。左半身が0〜23、右半身が24〜47。 キー番号の並びは視覚的な行ごとに左右交互で、マトリクス順とは一致しない。18〜20は欠番。 1つの例で「並びが違う」と「穴がある」の両方が出ている。

KMKの説明:

Split keyboards count as the total keyboard, not per side, the right side being offset by the number of keys on the left side, as if the rows were stacked.

QMKの分割も同じ構造。

Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns.

出典: https://docs.qmk.fm/features/split_keyboard

保存形式を order: string[] にした理由

旧案 keyMap: [{keyId, index}] は、欠番・重複・非連続をスキーマが許してしまう。 {k-a, 0}, {k-b, 0} が通る。

ELCの LEDChain.order で既に「並びの位置が番号」の形を採っている (eb96ff0)。同じ形に揃えた。 不変条件が構造として保証され、バリデーションが不要になる。

捨てた仮説

• 「IDXはdecal/ghostの区別を持つべきではないか」。decalはPHYが decal フラグを持っているので そこから分かる。ghostは何を意味するかがKLE由来で曖昧なので、IDXの側で規定しない。 order に挙げたキーだけが番号を持つ、で足りる
• 「VIAとの往復でキー番号が要るのでは」。VIAのプロトコルはrow/col指定なので、キー番号は出てこない。 ただし裏取りしていないので、ドキュメントには書かなかった