# 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`。

```python
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指定なので、キー番号は出てこない。
  ただし裏取りしていないので、ドキュメントには書かなかった