# KLE往復: 埋め込みなし + 取り込み時の照合

## 結論

- KLE JSONにBeyond KLE固有の情報(キーID、クラスター構造)を一切埋め込まない
- KLEは既存のビュワーとして使えればよい。KLEで触った時点でBeyond KLEのデータではない(ユーザーの線引き)
- KLE JSONの取り込みは、手元のPHYデータとの形状+ラベル照合で行う。照合できないキーはroot直下
- 構造の復元はベストエフォート。保証しない

## 案の比較

| 案 | 出典 | 問題 |
| --- | --- | --- |
| labelにIDを埋め込み、別ファイルのクラスターJSONと紐づけ | PHYレイヤー.md(旧) | VIAのlabelハックと同じ道。IDが長くなりラベルが見づらい |
| `_beyondkle` メタデータ + labels[8] のハイブリッド | kle-compatibility.md | 同上。独自プロパティはKLEが保存時に落とす可能性 |
| ゴーストキーにクラスター情報を格納 | kle-compatibility-analysis.md | 下記。所属情報が残らず、結局labelハックに戻る |
| 埋め込みなし + 照合(採用) | 今回 | KLEで大きく編集されると構造が失われる |
| metadataのnotesにクラスター表 + sm/sb/stにキーID | 今回の検討中に出た | 意味の違うフィールドの流用で、種類としては同じハック |

## 根拠

### 前提の変化

PHY座標モデルの決定(相対座標の木が正本)により、KLE JSONは導出物になった。
問いは「KLE JSONのどこにクラスターを埋めるか」から「KLEを経由して戻ってきたとき何を復元したいか」に変わった。
ユーザーの回答は「KLEはビュワーとして使えればよい」。これで埋め込み自体が不要になった。

### ゴーストキー案の穴

- キーの所属は `key.clusterId` という独自プロパティで持たせる設計だった(kle-compatibility-analysis.md の createCluster)。
    KLEのシリアライザは既知のプロパティしか書き出さないはずで(未確認)、保存時に所属が消える。
    残すには各キーのlabelにIDを入れることになり、labelハックに戻る
- 矩形に含まれるかで所属を判定する方法は、入れ子や回転があると曖昧になる
- ゴーストキー自体も labels[0]="CLUSTER_META"、labels[4]=JSON という形で、汚す対象がダミーキーに変わっただけ
- KLE JSONを読む他ツール(QMK変換、KiCad配置プラグインなど)がゴーストキーを実在するキーとして扱う懸念(未確認)。
    KLE JSONを出力する目的は互換性なので、偽のキーを混ぜるのは本末転倒

### KLEを改造するか自作するかとは独立

KLEを改造する場合でも、内部データと保存形式は自分で決められるので、ゴーストキーは要らない。
ゴーストキーが必要になるのは「改造していないKLEを通っても構造が残る」を要件にした場合だけで、その要件は今回捨てた。

## 未決のまま残したもの

- 照合基準の詳細(許容誤差、ラベルの扱い、複数候補の解決)。PHYレイヤー.md の未確認事項 P-2
- KLEが保存時にキー順を並べ替えるか(未確認)。配列順を照合に使えるかに関わる
- kle-compatibility.md / kle-compatibility-analysis.md の埋め込み案の記述は今回の決定と食い違うが、
    既存ドキュメントの再編は別タスクのため触っていない