Merge pull request #217 from m1sk9/fix/matrix-handshake-direction

docs(compatibility): clarify protocol version validation is Velocity

4 files changed, 38 insertions, 37 deletions

diff --git a/website/.vitepress/theme/components/CompatibilityMatrix.vue b/website/.vitepress/theme/components/CompatibilityMatrix.vue
index 0e91edc..9f1910c 100644
--- a/website/.vitepress/theme/components/CompatibilityMatrix.vue
+++ b/website/.vitepress/theme/components/CompatibilityMatrix.vue
@@ -31,10 +31,8 @@ const t = computed(() =>
         compatibleShort: 'OK',
         compatibilityHeader: 'Compatibility',
         reasonMajorMismatch: 'Major version mismatch',
-        reasonPaperTooNew: 'Paper newer — update Velocity first',
-        reasonVelocityTooNew: 'Velocity newer — update Paper',
-        reasonPaperTooOld: 'Paper too old',
-        reasonVelocityTooOld: 'Velocity too old',
+        reasonPaperTooNew: 'Paper protocol newer than Velocity — update Velocity first',
+        reasonPaperTooOld: 'Paper protocol older than Velocity accepts',
         legend: 'Legend',
         legendCompatible: 'Compatible — both can connect.',
         legendIncompatible: 'Incompatible — handshake will be rejected.',
@@ -55,10 +53,8 @@ const t = computed(() =>
         compatibleShort: 'OK',
         compatibilityHeader: '互換性',
         reasonMajorMismatch: 'MAJOR バージョン不一致',
-        reasonPaperTooNew: 'Paper が新しすぎる — Velocity を先に更新',
-        reasonVelocityTooNew: 'Velocity が新しすぎる — Paper を更新',
-        reasonPaperTooOld: 'Paper が古すぎる',
-        reasonVelocityTooOld: 'Velocity が古すぎる',
+        reasonPaperTooNew: 'Paper のプロトコルが Velocity より新しい — Velocity を先に更新',
+        reasonPaperTooOld: 'Paper のプロトコルが Velocity の許容範囲より古い',
         legend: '凡例',
         legendCompatible: '互換 — 接続可能．',
         legendIncompatible: '非互換 — ハンドシェイクで拒否されます．',
@@ -89,12 +85,8 @@ function reasonLabel(result: CompatibilityResult): string {
       return t.value.reasonMajorMismatch;
     case 'paper-too-new':
       return t.value.reasonPaperTooNew;
-    case 'velocity-too-new':
-      return t.value.reasonVelocityTooNew;
     case 'paper-too-old':
       return t.value.reasonPaperTooOld;
-    case 'velocity-too-old':
-      return t.value.reasonVelocityTooOld;
     default:
       return '';
   }
diff --git a/website/.vitepress/theme/components/useCompatibilityData.ts b/website/.vitepress/theme/components/useCompatibilityData.ts
index 452e8b4..d0de01d 100644
--- a/website/.vitepress/theme/components/useCompatibilityData.ts
+++ b/website/.vitepress/theme/components/useCompatibilityData.ts
@@ -134,25 +134,18 @@ export function useCompatibilityData() {
   return { data, loading, error };
 }
 
-export type CompatibilityResult = 'compatible' | 'major-mismatch' | 'paper-too-new' | 'velocity-too-new' | 'paper-too-old' | 'velocity-too-old';
+export type CompatibilityResult = 'compatible' | 'major-mismatch' | 'paper-too-new' | 'paper-too-old';
 
+// Mirrors the gatekeeping done by Velocity in
+// platform-velocity/.../PluginMessageHandler.kt — Paper does not validate.
 export function checkCompatibility(
   paper: ProtocolVersion,
   velocity: ProtocolVersion,
 ): CompatibilityResult {
   if (paper.major !== velocity.major) return 'major-mismatch';
-
-  const paperAcceptsVelocity =
-    velocity.minor >= paper.minSupportedMinor && velocity.minor <= paper.minor;
-  const velocityAcceptsPaper =
-    paper.minor >= velocity.minSupportedMinor && paper.minor <= velocity.minor;
-
-  if (paperAcceptsVelocity && velocityAcceptsPaper) return 'compatible';
-  if (!velocityAcceptsPaper && paper.minor > velocity.minor) return 'paper-too-new';
-  if (!paperAcceptsVelocity && velocity.minor > paper.minor) return 'velocity-too-new';
-  if (!velocityAcceptsPaper && paper.minor < velocity.minSupportedMinor) return 'paper-too-old';
-  if (!paperAcceptsVelocity && velocity.minor < paper.minSupportedMinor) return 'velocity-too-old';
-  return 'major-mismatch';
+  if (paper.minor > velocity.minor) return 'paper-too-new';
+  if (paper.minor < velocity.minSupportedMinor) return 'paper-too-old';
+  return 'compatible';
 }
 
 export function isCompatible(
diff --git a/website/src/docs/reference/compatibility.md b/website/src/docs/reference/compatibility.md
index dc0c3b2..25ca957 100644
--- a/website/src/docs/reference/compatibility.md
+++ b/website/src/docs/reference/compatibility.md
@@ -6,6 +6,10 @@ layout: doc
 
 LunaticChat の Paper プラグインと Velocity プラグインは独立にバージョン管理されています．それぞれの組み合わせが動作するかどうかは，両プラグインに埋め込まれた**プロトコルバージョン**で判定されます．
 
+::: warning プラグインバージョン ≠ プロトコルバージョン
+**プラグインバージョン** (例: Paper v1.2.0) と **プロトコルバージョン** (例: 1.0.0) は別物です．プラグイン側のリリースを重ねてもプロトコルが変わらなければ互換性は維持されます．互換性を決めるのはプロトコルバージョンのみです．
+:::
+
 ## 結論から
 
 - **両プラグインの最新版同士は常に互換性があります．** 迷ったら両方を最新にしてください．
@@ -20,15 +24,19 @@ LunaticChat の Paper プラグインと Velocity プラグインは独立にバ
 
 ## プロトコルバージョンとは
 
-Paper / Velocity 間の通信は LunaticChat 独自のプラグインメッセージプロトコルで行われています．プロトコルにはセマンティックバージョニング (`MAJOR.MINOR.PATCH`) が振られており，接続時のハンドシェイクで両者のバージョンが照合されます．
+Paper / Velocity 間の通信は LunaticChat 独自のプラグインメッセージプロトコルで行われています．プロトコルにはセマンティックバージョニング (`MAJOR.MINOR.PATCH`) が振られており，接続時のハンドシェイクで Velocity 側がバージョンを照合します．
+
+::: tip 互換性チェックは Velocity 側のみ
+互換性判定をしているのは Velocity 側のみです．Paper 側はハンドシェイクを送るだけで，バージョンチェックはしません．つまり「Velocity が Paper のプロトコルを受け入れられるか」がそのまま接続可否になります．
+:::
 
-判定ルールは以下です：
+判定ルールは以下です（Velocity 視点）：
 
 - **MAJOR** が一致すること
-- 相手の **MINOR** が自分の `MIN_SUPPORTED_MINOR` 以上かつ自分の `MINOR` 以下であること
+- Paper の **MINOR** が，Velocity の `MIN_SUPPORTED_MINOR` 以上かつ Velocity の `MINOR` 以下であること
 - **PATCH** は判定に影響しない
 
-`MIN_SUPPORTED_MINOR` は「どこまで古い MINOR を受け入れるか」を示す値で，ローリングアップデート中の猶予期間を作るために使われます．
+`MIN_SUPPORTED_MINOR` は「Velocity がどこまで古い Paper の MINOR を受け入れるか」を示す値で，ローリングアップデート中の猶予期間を作るために使われます．
 
 ### バージョンバンプの基準
 
@@ -50,8 +58,8 @@ Paper / Velocity 間の通信は LunaticChat 独自のプラグインメッセ�
 接続時は以下の流れで互換性が確認されます：
 
 1. Paper サーバー起動時に Velocity に対してハンドシェイクを送信
-2. Velocity が自身のプロトコルバージョンと照合
-3. 不一致の場合は接続が拒否され，状態が `FAILED` になる
+2. Velocity が Paper のプロトコルバージョンを自身のものと照合
+3. 不一致の場合は Velocity が接続を拒否し，Paper 側の状態が `FAILED` になる
 4. ハンドシェイクのタイムアウトは 5 秒
 
 接続状態は `/lcv status` で確認できます．詳細は [Velocity 連携](/docs/features/velocity#接続状態) を参照してください．
diff --git a/website/src/en/docs/reference/compatibility.md b/website/src/en/docs/reference/compatibility.md
index a2b1e8f..ac7002d 100644
--- a/website/src/en/docs/reference/compatibility.md
+++ b/website/src/en/docs/reference/compatibility.md
@@ -6,6 +6,10 @@ layout: doc
 
 The Paper and Velocity plugins of LunaticChat are versioned independently. Whether a given combination works is determined by the **protocol version** embedded in each plugin.
 
+::: warning Plugin version ≠ protocol version
+The **plugin version** (e.g., Paper v1.2.0) and the **protocol version** (e.g., 1.0.0) are different things. New plugin releases do not necessarily change the protocol — and only the protocol version determines compatibility.
+:::
+
 ## TL;DR
 
 - **The latest Paper and the latest Velocity are always compatible.** When in doubt, use the latest of both.
@@ -20,15 +24,19 @@ Each cell indicates whether the corresponding Paper × Velocity combination can
 
 ## What Is a Protocol Version?
 
-Paper and Velocity communicate via a LunaticChat-specific plugin messaging protocol. The protocol carries a semantic version (`MAJOR.MINOR.PATCH`), and a handshake at connection time validates both sides.
+Paper and Velocity communicate via a LunaticChat-specific plugin messaging protocol. The protocol carries a semantic version (`MAJOR.MINOR.PATCH`), and at connection time Velocity validates the protocol version sent by Paper.
+
+::: tip Velocity is the only side that checks
+Only Velocity performs the compatibility check. Paper just sends a handshake — it does not validate Velocity's version. So the question reduces to: "Does Velocity accept Paper's protocol version?"
+:::
 
-The rules are:
+The rules (from Velocity's perspective) are:
 
 - **MAJOR** must match exactly
-- The remote **MINOR** must be at least `MIN_SUPPORTED_MINOR` and at most the local `MINOR`
+- Paper's **MINOR** must be at least Velocity's `MIN_SUPPORTED_MINOR` and at most Velocity's `MINOR`
 - **PATCH** does not affect compatibility
 
-`MIN_SUPPORTED_MINOR` controls how far back the local plugin accepts older peers, providing a grace window during rolling updates.
+`MIN_SUPPORTED_MINOR` controls how far back Velocity accepts older Paper peers, providing a grace window during rolling updates.
 
 ### Version Bump Rules
 
@@ -50,8 +58,8 @@ The rules are:
 Compatibility is checked at connection time:
 
 1. The Paper server sends a handshake to Velocity at startup
-2. Velocity validates the protocol version against its own
-3. On mismatch, the connection is rejected and the state becomes `FAILED`
+2. Velocity validates Paper's protocol version against its own
+3. On mismatch, Velocity rejects the connection and Paper's state becomes `FAILED`
 4. The handshake timeout is 5 seconds
 
 Live connection state is available via `/lcv status`. See [Velocity Integration](/en/docs/features/velocity#connection-states) for details.