IDX: キー番号の正本としてIDXレイヤーを確定し、MAPの参照をPHYへ移す

キー番号はPHYの幾何からもELCの配線からも導出できない決めごとなので、IDXが正本を持つ。公開した基板のキー番号は他人のキーマップが依存する公開インターフェースであり、出力のたびに生成し直さず固定する。「最も重要な抽象化層」「最も欠けている層」という位置づけは誤りだったので落とした。 QMKのLAYOUTマクロの引数順、ZMKのmatrix transformのmap、KMKのcoord_mappingとして既に存在していて、形式化されていないだけである。あわせて2点。MAPはキー番号ではなくPHYのキーIDを参照する(IDXへの挿入でMAPがずれないため)。 IDXの保存形式は order: string[] とし、ELCのLEDChain.orderと同じく並びの位置を番号とする。 phase1-json-schema.md の P-1 を解消。 Journal: journal/2026-09-21-idx-necessity.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-21 08:52:27 +09:00
parent fdd3c7def1
commit 2eb2867c13
6 changed files with 263 additions and 54 deletions
@@ -12,6 +12,8 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
 |---|---|
 | `keyboard-design-layers.md` | レイヤー構造とツール分割方針(最上位) |
 | `PHYレイヤー.md` | PHY層の仕様 |
+| `ELCレイヤー.md` | ELC層の仕様 |
+| `IDXレイヤー.md` | IDX層の仕様 |
 | `phase1-json-schema.md` | 各層のJSON Schema |
 | `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
 | `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
@@ -0,0 +1,97 @@
+# IDXレイヤー
+
+## 概要
+
+IDXレイヤーは、PHYのキーに「キー番号」を与える。キー番号は、キーマップがキーを指すための識別子である。
+
+キー番号は他のどの情報からも導出できない。設計者が決める並び順そのものであり、
+そのためIDXが正本として持つ。ELCのrow/colが「配線から決まるので出力時に導出する」のと、
+理由が裏返しの関係にある。
+
+IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。
+
+## キー番号は公開インターフェース
+
+基板を公開すると、他人が書いたキーマップがそのキー番号に依存する。
+番号を振り直すと、既存のキーマップが別のキーを指す。
+
+そのためキー番号は、出力のたびに生成し直す派生情報として扱わず、固定した正本として保存する。
+
+## 幾何から導出しない
+
+PHYの座標・ツリー順をキー番号に使わない。
+
+クラスターは幾何の編集単位であって論理的な行ではない。親指キーをまとめて回転させるために
+クラスターへ出し入れすると、ツリー順が変わる。ツリー順が番号なら、そこでキーマップがずれる。
+
+座標から行を判定する方法は、カラムスタッガードや曲線配列で破綻する。これはKLEの問題点として
+`keyboard-design-layers.md` に挙げたものと同じ性質の話である。
+
+## 配線から導出しない
+
+ELCのマトリクス位置をキー番号に使わない。
+
+- マトリクスの並びとキー番号の並びは一致しない。分割キーボードでは、マトリクスは片方の半身の行を
+  並べてからもう片方の行を並べるが、キー番号は視覚的な行ごとに左右を交互に取るのが通例である
+- マトリクスには欠番がある。キー番号は実在するキーに対して連続だが、マトリクスは疎である
+- 基板リビジョンでピンを差し替えたときに、キー番号が動いてはならない
+
+row / col 自体がELCの正本ではなく出力時の派生情報である。派生情報から番号を導くと二重に不安定になる。
+
+## 出力先が要求する形
+
+3つの処理系はいずれも「マトリクス位置の順序付きリスト」を要求し、その並びの位置をキー番号とする。
+どれも人手で書かれており、他の情報から導出されていない。Firmware Generatorはこれらを出力する。
+
+| 処理系 | キー番号を決めているもの |
+| --- | --- |
+| QMK | `LAYOUT` マクロの引数順 / `keyboard.json` の `layouts.<NAME>.layout[]` の配列順 |
+| ZMK | matrix transform の `map` の並び順 |
+| KMK | `coord_mapping` の並び順 |
+
+## 他レイヤーとの関係
+
+IDXはPHYのキーIDだけを参照する。ELCを参照しない。
+
+MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。
+キーマップを配列として出力するとき、IDXの並び順で並べ替える。
+これにより、IDXにキーを挿入して番号がずれても、MAPは書き換えずに済む。
+
+MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。
+IDXの `order` と突き合わせて検出できる。
+
+## 持たないもの
+
+- マトリクス座標 (row / col)。ELCの配線から出力時に割り当てる
+- LEDの識別番号。ELCが正本を持つ
+- キーコード (MAPが持つ)
+- キーの物理的な位置とサイズ (PHYが持つ)
+
+## 保存形式
+
+```ts
+type IDX = {
+    order: string[]   // PHYのキーID。並びの位置がキー番号
+}
+```
+
+並びの位置を番号とする形は、ELCの `LEDChain.order` と同じ形である。
+欠番・重複・番号の飛びが構造として起こらない。
+
+`order` に挙げたキーだけが番号を持つ。PHYの部品ノードと `decal` のキーは対象にならない。
+
+## 検討済み・非採用
+
+- PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
+- ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md)
+- `keyId` と `index` の対を並べる形 (journal/2026-09-21-idx-necessity.md)
+- MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md)
+
+## 未確認事項
+
+### P-1 レイアウトバリアントの扱い
+
+- 位置づけ: 未解決の問い。本文は単一レイアウトだけを前提にしている
+- 現状の認識: QMKの `LAYOUT_60_ansi` / `LAYOUT_60_iso` のように、1つの基板が複数のキー番号空間を持つ場合がある。
+  1つのPHY+ELCに複数のIDXがぶら下がる形になりそうだが、PHYが代替キーをどう持つかが今のPHY仕様にない
+- 格上げ条件: PHYの代替キーの表現とあわせて、マルチレイアウトの扱いをユーザーと決める
@@ -0,0 +1,115 @@
+# 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指定なので、キー番号は出てこない。
+  ただし裏取りしていないので、ドキュメントには書かなかった
@@ -16,8 +16,8 @@

 ## レイヤー構造

-レイヤーは一列に積み上がらない。ELCとIDXはそれぞれ独立にPHYを参照する。
-ELCはIDXを参照せず、IDXもELCを参照しない。
+レイヤーは一列に積み上がらない。ELC・IDX・MAPはそれぞれ独立にPHYを参照する。
+ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照しない。
 他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。

 ### 1. PHYレイヤー (物理配置)
@@ -37,18 +37,22 @@ ELCはIDXを参照せず、IDXもELCを参照しない。

 ### 3. IDXレイヤー (キー識別)

- **役割**: PHYのキーと"キー番号"の対応付け
+- **役割**: PHYのキーに"キー番号"を与える
 - **入力**: PHYのキーID
- **重要性**: 物理世界と論理世界を繋ぐ最も重要な抽象化層
- **出力**: キーIDとキー番号の対応
- **備考**: 現状のエコシステムで最も欠けている層
+- **対応ツール**: QMKの `LAYOUT` マクロ、ZMKの matrix transform、KMKの `coord_mapping`
+- **出力**: 番号を振るキーの並び。並びの位置がキー番号
+- **備考**: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる)
+- **備考**: キー番号は公開インターフェースであり、出力のたびに生成し直さず固定する
 - **備考**: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)
+- **備考**: 既存のエコシステムでは、この並びが `LAYOUT` マクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層

 ### 4. MAPレイヤー (キーマップ)

- **役割**: キー番号とキーコードの対応
+- **役割**: キーとキーコードの対応
+- **入力**: PHYのキーID
 - **対応ツール**: ファームウェア、VIA、Remap
- **出力**: レイヤー別キーコード配列
+- **出力**: レイヤー別キーコード
+- **備考**: キーの参照にキー番号を使わない。配列としての並べ替えは、出力時にIDXの並び順で行う

 ### 5. IMEレイヤー (入力変換)

@@ -81,7 +85,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。

 #### Keymap Designer

- キー番号のリストを入力
+- PHY JSONを入力
 - レイヤー別キーコード割り当て
 - VIA/Remapとの互換性
 - 出力: MAP JSON
@@ -111,11 +115,11 @@ PHY → ELC

 PHY → IDX
  Input:  キーID + 配置
-  Output: キーIDとキー番号の対応
+  Output: 番号を振るキーIDの並び

-IDX → MAP
-  Input:  キー番号のリスト
-  Output: レイヤー別キーコード配列
+PHY → MAP
+  Input:  キーID
+  Output: レイヤー別キーコード

 All → Firmware
  Output: QMK keyboard.json / VIA JSON / KMK .py
@@ -57,9 +57,12 @@
  - マトリックス定義（ROW/COL）
  - ピン配置設定
  - 物理レイアウト定義
- **現在の課題**: KLEとファームウェア設定の手動変換
+  - キーマップ配列の並び順を決める（QMKなら `LAYOUT` マクロの引数順、ZMKなら matrix transform の
+    `map`、KMKなら `coord_mapping`）
+- **現在の課題**: KLEとファームウェア設定の手動変換。並び順は手書きで、引数の数え間違いがそのまま
+  キーのずれになる
 - **Beyond KLE対応**: **PHY** + **IDX** + **ELC** → ファームウェア自動生成。
-  ROW/COLはELCの配線から出力時に割り当てる
+  ROW/COLはELCの配線から出力時に割り当てる。並び順は**IDXレイヤー**が正本として持つ

 #### b) キーマップ設定

@@ -68,7 +71,7 @@
  - 各キーへのキーコード割り当て
  - レイヤー設計
  - マクロ・特殊機能の設定
- **Beyond KLE対応**: **MAPレイヤー**
+- **Beyond KLE対応**: **MAPレイヤー**。キーの参照にはPHYのキーIDを使い、配列への並べ替えは出力時にIDXの順で行う

 ### 4. 製造・組み立て段階

@@ -5,11 +5,11 @@
 ```txt
 PHY (物理配置)
 ├─→ ELC (電気配線)
- └─→ IDX (キー識別)
-      └─→ MAP (キーマップ)
+ ├─→ IDX (キー識別)
+ └─→ MAP (キーマップ)
 ```

-ELCとIDXはどちらもPHYを参照する。ELCはIDXを参照しない。
+ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAPもIDXを参照しない。
 ファームウェアやVIA/Remap向けの出力は、各レイヤーの情報を統合して生成する。
 他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。

@@ -316,9 +316,10 @@ ELCとIDXはどちらもPHYを参照する。ELCはIDXを参照しない。

 ## 2. IDXレイヤー JSON Schema

-IDXが持つのは、PHYのキーとキー番号の対応だけとする [推測:P-1]。
-マトリックス座標(row/col)とLEDの識別番号はここに置かない。どちらも配線で決まる情報で、
-row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を持つ。
+各フィールドの意味は `IDXレイヤー.md` を正とする。
+
+番号を振るキーの並びだけを持つ。並びの位置がキー番号になるため、欠番・重複・番号の飛びは
+構造として起こらない。

 ### 基本構造

@@ -327,9 +328,9 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://beyond-kle.org/schemas/idx-layer.json",
  "title": "IDX Layer - Key Identification",
-  "description": "Mapping between PHY keys and key numbers",
+  "description": "Ordered list of PHY keys; the position in the list is the key number",
  "type": "object",
-  "required": ["version", "phyReference", "keyMap"],
+  "required": ["version", "phyReference", "order"],
  "properties": {
    "version": { "type": "string" },
    "phyReference": {
@@ -340,27 +341,12 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
        "checksum": { "type": "string" }
      }
    },
-    "keyMap": {
+    "order": {
      "type": "array",
+      "uniqueItems": true,
      "items": {
-        "$ref": "#/$defs/keyMapping"
-      }
-    }
-  },
-  "$defs": {
-    "keyMapping": {
-      "type": "object",
-      "required": ["keyId", "index"],
-      "properties": {
-        "keyId": {
-          "type": "string",
-          "description": "Reference to PHY layer key ID"
-        },
-        "index": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Key number"
-        }
+        "type": "string",
+        "description": "Reference to PHY layer key ID"
      }
    }
  }
@@ -518,6 +504,9 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を

 ## 4. MAPレイヤー JSON Schema

+キーの参照にはPHYのキーIDを使う。キー番号は参照しない。
+配列としての並べ替えは、ファームウェア出力時にIDXの並び順で行う。
+
 ### 基本構造

 ```json
@@ -527,10 +516,10 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
  "title": "MAP Layer - Keymap Configuration",
  "description": "Key code assignments and layers",
  "type": "object",
-  "required": ["version", "idxReference", "layers"],
+  "required": ["version", "phyReference", "layers"],
  "properties": {
    "version": { "type": "string" },
-    "idxReference": {
+    "phyReference": {
      "type": "object",
      "required": ["source", "checksum"],
      "properties": {
@@ -562,9 +551,12 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
    },
    "keyAssignment": {
      "type": "object",
-      "required": ["keyIndex", "keycode"],
+      "required": ["keyId", "keycode"],
      "properties": {
-        "keyIndex": { "type": "integer" },
+        "keyId": {
+          "type": "string",
+          "description": "Reference to PHY layer key ID"
+        },
        "keycode": { "type": "string" }
      }
    }
@@ -577,7 +569,7 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
 ### PHY → IDX変換

 1. PHYレイヤーからキーのリストを取得
-2. 各キーにキー番号を割り当て
+2. 番号を振るキーを選び、並び順を決める

 ### PHY → ELC変換

@@ -588,7 +580,7 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を
 ### IDX + ELC + MAP → ファームウェア出力

 1. ELCの配線から、ターゲットが要求する row / col を割り当て
-2. キー番号の配列とキーマップ配列の生成
+2. IDXの並び順に従って、MAPのキーコードを配列へ並べ替え
 3. VIA/QMK形式への出力

 ## 次のステップ
@@ -600,8 +592,4 @@ row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を

 ## 未確認事項

-### P-1 IDXがキー番号以外に持つものがあるか
-
- 位置づけ: 本文「2. IDXレイヤー JSON Schema」が前提にしている。IDXには仕様ドキュメントがなく、
-  決定済みの情報(row/col と LEDの番号はELC)から引き算した最小形として書いている
- 格上げ条件: IDXレイヤーの仕様をユーザーと決め、`IDXレイヤー.md` に書く
+(なし)