From 1f0edeb8163acc17429aafe0c9469120f26a94cf Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Tue, 13 Oct 2026 04:44:11 +0800
Subject: [PATCH 1/5] docs: explain legacy graphid preflight

- describe cold-open and replay checks
- preserve evidence when preflight refuses
- clarify upgrade and recovery boundaries
---
 content/cn/docs/config/config-backend-hstore.md | 12 ++++++++++++
 content/en/docs/config/config-backend-hstore.md | 14 ++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md
index 59a0131b08..f46f930717 100644
--- a/content/cn/docs/config/config-backend-hstore.md
+++ b/content/cn/docs/config/config-backend-hstore.md
@@ -208,3 +208,15 @@ curl http://localhost:8080/metrics/backend
 ```
 
 响应中的 `nodes` 就是 PD 返回的活跃 Store 数量。`nodes` 为 `0` 说明 Server 连上了 PD，但 PD 中没有状态为 `Up` 的 Store，通常是 Store 节点还没注册，或者因为不在 PD 的 `pd.initial-store-list` 中而注册成了 `Pending`。
+
+包含旧 GraphID 预检修复的 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
+首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本。发现保留前缀 `FFFE` 的旧数据时会拒绝操作；
+如果选中的不完整 DB 版本缺少 `CURRENT`、会遮蔽仍保留的有效版本，也会拒绝。
+这针对受影响的旧写入路径，不表示所有 1.7 数据库都需要迁移，持久化 ID 格式保持不变。
+
+遇到拒绝时，保留原始数据 DB 版本、元数据、WAL，以及输入快照和暂存副本，在恢复写入或回放前调查相关写入与升级历史。
+不要删除图到 ID 的映射，也不要把所有保留前缀行归给同一个图，因为不同图可能共享该前缀。Store/Raft 位置元数据可能已在预检前更新，因此整个启动流程并非只读。
+预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。
+
+详细行为与处置依据见[预检修复](https://github.com/hugegraph/hugegraph/pull/301)和
+[仓库升级指南](https://github.com/hugegraph/hugegraph/blob/52bc94ce5078f879b9f9ee18f1049e8da7397344/docs/store-graphid-upgrade.md)。
diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md
index 189ade32ce..50aabae5cf 100644
--- a/content/en/docs/config/config-backend-hstore.md
+++ b/content/en/docs/config/config-backend-hstore.md
@@ -246,3 +246,17 @@ curl http://localhost:8080/metrics/backend
 The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
 Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
 yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
+resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
+Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
+migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
+
+See the [preflight change](https://github.com/hugegraph/hugegraph/pull/301) and the
+[repository upgrade guide](https://github.com/hugegraph/hugegraph/blob/52bc94ce5078f879b9f9ee18f1049e8da7397344/docs/store-graphid-upgrade.md) for details.

From 6596f60b6d0416b7368697bb4861b411889bdc72 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Tue, 13 Oct 2026 05:42:40 +0800
Subject: [PATCH 2/5] docs: link the current graphid upgrade guide

- point both language pages to the validated source
- retain the established upgrade warning text
- keep the code and website guidance aligned
---
 content/cn/docs/config/config-backend-hstore.md | 2 +-
 content/en/docs/config/config-backend-hstore.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md
index f46f930717..4c6f9b9570 100644
--- a/content/cn/docs/config/config-backend-hstore.md
+++ b/content/cn/docs/config/config-backend-hstore.md
@@ -219,4 +219,4 @@ curl http://localhost:8080/metrics/backend
 预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。
 
 详细行为与处置依据见[预检修复](https://github.com/hugegraph/hugegraph/pull/301)和
-[仓库升级指南](https://github.com/hugegraph/hugegraph/blob/52bc94ce5078f879b9f9ee18f1049e8da7397344/docs/store-graphid-upgrade.md)。
+[仓库升级指南](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md
index 50aabae5cf..9ecc34e125 100644
--- a/content/en/docs/config/config-backend-hstore.md
+++ b/content/en/docs/config/config-backend-hstore.md
@@ -259,4 +259,4 @@ Store/Raft location metadata may already have been updated before the check, so
 migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
 
 See the [preflight change](https://github.com/hugegraph/hugegraph/pull/301) and the
-[repository upgrade guide](https://github.com/hugegraph/hugegraph/blob/52bc94ce5078f879b9f9ee18f1049e8da7397344/docs/store-graphid-upgrade.md) for details.
+[repository upgrade guide](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md) for details.

From 0f296459c2adcd515429c04857d875b2fff289ab Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Tue, 13 Oct 2026 12:22:50 +0800
Subject: [PATCH 3/5] docs: clarify store preflight availability

- scope the guard to builds containing the paired fix
- link the Apache implementation and upgrade guide
- add matching English and Chinese section headings
---
 content/cn/docs/config/config-backend-hstore.md | 10 +++++++---
 content/en/docs/config/config-backend-hstore.md | 14 +++++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md
index 4c6f9b9570..0ee5563f44 100644
--- a/content/cn/docs/config/config-backend-hstore.md
+++ b/content/cn/docs/config/config-backend-hstore.md
@@ -209,7 +209,12 @@ curl http://localhost:8080/metrics/backend
 
 响应中的 `nodes` 就是 PD 返回的活跃 Store 数量。`nodes` 为 `0` 说明 Server 连上了 PD，但 PD 中没有状态为 `Up` 的 Store，通常是 Store 节点还没注册，或者因为不在 PD 的 `pd.initial-store-list` 中而注册成了 `Pending`。
 
-包含旧 GraphID 预检修复的 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
+### 9 旧 GraphID 升级预检
+
+以下检查仅适用于包含 [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330) 所提实现的 Store 构建。
+该修复尚未合入 Apache HugeGraph，也未包含在 Apache 发行版中。更早的 1.8 构建不保证具备该保护；依赖下述拒绝行为前，先确认所用构建包含该修复。
+
+这些 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
 首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本。发现保留前缀 `FFFE` 的旧数据时会拒绝操作；
 如果选中的不完整 DB 版本缺少 `CURRENT`、会遮蔽仍保留的有效版本，也会拒绝。
 这针对受影响的旧写入路径，不表示所有 1.7 数据库都需要迁移，持久化 ID 格式保持不变。
@@ -218,5 +223,4 @@ curl http://localhost:8080/metrics/backend
 不要删除图到 ID 的映射，也不要把所有保留前缀行归给同一个图，因为不同图可能共享该前缀。Store/Raft 位置元数据可能已在预检前更新，因此整个启动流程并非只读。
 预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。
 
-详细行为与处置依据见[预检修复](https://github.com/hugegraph/hugegraph/pull/301)和
-[仓库升级指南](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
+详细行为与处置依据见[所提源码版本的升级指南](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md
index 9ecc34e125..bf6ac1acf9 100644
--- a/content/en/docs/config/config-backend-hstore.md
+++ b/content/en/docs/config/config-backend-hstore.md
@@ -247,7 +247,14 @@ The `nodes` value in the response is the count of active stores PD returns. A `n
 Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
 yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
 
-Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
+### 9 Legacy GraphID upgrade preflight
+
+The following checks apply only to Store builds containing the implementation proposed in
+[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
+This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
+build contains the fix before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
 partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
 all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
 An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
@@ -258,5 +265,6 @@ resuming writes or replay. Do not delete graph-to-ID mappings or assign all rese
 Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
 migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
 
-See the [preflight change](https://github.com/hugegraph/hugegraph/pull/301) and the
-[repository upgrade guide](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md) for details.
+See the
+[guide for the proposed revision](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
+for details.

From 523754364cef25a3d3620c3ca8943cfac03f7aef Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Tue, 13 Oct 2026 23:26:08 +0800
Subject: [PATCH 4/5] docs: clarify graphid preflight availability

- link the Apache pinned upgrade guide
- clarify release and master guard availability
- retain deployment-specific upgrade validation
---
 content/cn/docs/config/config-backend-hstore.md | 6 ++++--
 content/en/docs/config/config-backend-hstore.md | 6 +++---
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md
index 0ee5563f44..d85efedee3 100644
--- a/content/cn/docs/config/config-backend-hstore.md
+++ b/content/cn/docs/config/config-backend-hstore.md
@@ -212,7 +212,8 @@ curl http://localhost:8080/metrics/backend
 ### 9 旧 GraphID 升级预检
 
 以下检查仅适用于包含 [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330) 所提实现的 Store 构建。
-该修复尚未合入 Apache HugeGraph，也未包含在 Apache 发行版中。更早的 1.8 构建不保证具备该保护；依赖下述拒绝行为前，先确认所用构建包含该修复。
+该修复尚未合入。已发布的 1.7.0 Store 和 #3330 合入前的 Apache `master` 构建不包含此预检保护。
+依赖下述拒绝行为前，请使用包含该修复的构建。
 
 这些 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
 首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本。发现保留前缀 `FFFE` 的旧数据时会拒绝操作；
@@ -223,4 +224,5 @@ curl http://localhost:8080/metrics/backend
 不要删除图到 ID 的映射，也不要把所有保留前缀行归给同一个图，因为不同图可能共享该前缀。Store/Raft 位置元数据可能已在预检前更新，因此整个启动流程并非只读。
 预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。
 
-详细行为与处置依据见[所提源码版本的升级指南](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
+详细行为与处置依据见
+[所提源码版本的升级指南](https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md
index bf6ac1acf9..0b084326a1 100644
--- a/content/en/docs/config/config-backend-hstore.md
+++ b/content/en/docs/config/config-backend-hstore.md
@@ -251,8 +251,8 @@ yet, or registered as `Pending` because they are not in PD's `pd.initial-store-l
 
 The following checks apply only to Store builds containing the implementation proposed in
 [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
-This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
-build contains the fix before relying on the refusal behavior below.
+This change is not yet merged. The released 1.7.0 Store and Apache `master` builds before #3330 is merged do not contain this preflight guard.
+Use a build containing the fix before relying on the refusal behavior below.
 
 These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
 partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
@@ -266,5 +266,5 @@ Store/Raft location metadata may already have been updated before the check, so
 migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
 
 See the
-[guide for the proposed revision](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
+[guide for the proposed revision](https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
 for details.

From d409ef8b553a2d647bc92a2ebd63fb97e8a6aed7 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Wed, 14 Oct 2026 04:10:24 +0800
Subject: [PATCH 5/5] docs: clean unreleased PR references in legacy GraphID
 preflight

---
 content/cn/docs/config/config-backend-hstore.md |  8 +++-----
 content/en/docs/config/config-backend-hstore.md | 11 ++++-------
 2 files changed, 7 insertions(+), 12 deletions(-)

diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md
index d85efedee3..d4606a3aa6 100644
--- a/content/cn/docs/config/config-backend-hstore.md
+++ b/content/cn/docs/config/config-backend-hstore.md
@@ -211,9 +211,8 @@ curl http://localhost:8080/metrics/backend
 
 ### 9 旧 GraphID 升级预检
 
-以下检查仅适用于包含 [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330) 所提实现的 Store 构建。
-该修复尚未合入。已发布的 1.7.0 Store 和 #3330 合入前的 Apache `master` 构建不包含此预检保护。
-依赖下述拒绝行为前，请使用包含该修复的构建。
+HugeGraph-Store 在启动和升级流程中提供旧版 GraphID 的安全预检保护机制。已发布的 1.7.0 及更早版本不包含此预检保护。
+依赖下述拒绝行为前，请确认使用支持该特性的 Store 构建。
 
 这些 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
 首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本。发现保留前缀 `FFFE` 的旧数据时会拒绝操作；
@@ -224,5 +223,4 @@ curl http://localhost:8080/metrics/backend
 不要删除图到 ID 的映射，也不要把所有保留前缀行归给同一个图，因为不同图可能共享该前缀。Store/Raft 位置元数据可能已在预检前更新，因此整个启动流程并非只读。
 预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。
 
-详细行为与处置依据见
-[所提源码版本的升级指南](https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
+详细行为与处置依据见官方升级指南中的 [Store GraphID 升级说明](https://github.com/apache/hugegraph/blob/master/docs/store-graphid-upgrade.md)。
diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md
index 0b084326a1..72d15e6331 100644
--- a/content/en/docs/config/config-backend-hstore.md
+++ b/content/en/docs/config/config-backend-hstore.md
@@ -249,10 +249,9 @@ yet, or registered as `Pending` because they are not in PD's `pd.initial-store-l
 
 ### 9 Legacy GraphID upgrade preflight
 
-The following checks apply only to Store builds containing the implementation proposed in
-[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
-This change is not yet merged. The released 1.7.0 Store and Apache `master` builds before #3330 is merged do not contain this preflight guard.
-Use a build containing the fix before relying on the refusal behavior below.
+HugeGraph-Store provides legacy GraphID upgrade preflight checks during bootstrap and upgrade processes.
+Released 1.7.0 and earlier Store builds do not contain this preflight guard.
+Use a Store build supporting this capability before relying on the refusal behavior below.
 
 These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
 partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
@@ -265,6 +264,4 @@ resuming writes or replay. Do not delete graph-to-ID mappings or assign all rese
 Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
 migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
 
-See the
-[guide for the proposed revision](https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
-for details.
+See the [Store GraphID upgrade documentation](https://github.com/apache/hugegraph/blob/master/docs/store-graphid-upgrade.md) for details.