This is an automated email from the ASF dual-hosted git repository.
zyxxoo pushed a commit to branch refactor/rust-rewrite-design
in repository https://gitbox.apache.org/repos/asf/hugegraph.git
The following commit(s) were added to refs/heads/refactor/rust-rewrite-design
by this push:
new e2e81bc25 docs(test): audit server pd store assets and oracle closure
e2e81bc25 is described below
commit e2e81bc259ea486274bb7117d5dfc260c254b900
Author: vaughn <[email protected]>
AuthorDate: Thu Sep 10 01:37:50 2026 +0800
docs(test): audit server pd store assets and oracle closure
---
docs/rust-rewrite-oracle-finalization.md | 75 ++++++++++++++++++++++++++++++++
docs/rust-rewrite-pd-store-test-audit.md | 43 ++++++++++++++++++
docs/rust-rewrite-server-test-audit.md | 32 ++++++++++++++
3 files changed, 150 insertions(+)
diff --git a/docs/rust-rewrite-oracle-finalization.md
b/docs/rust-rewrite-oracle-finalization.md
new file mode 100644
index 000000000..28f7c37d9
--- /dev/null
+++ b/docs/rust-rewrite-oracle-finalization.md
@@ -0,0 +1,75 @@
+# Rust 重构测试 Oracle 与契约追踪最终化方案
+
+## 目标
+
+将测试资产盘点从文件清单升级为可审计的“能力—契约—测试—Oracle—结果”证据链。该文档定义字段、状态机、独立
Oracle、负向测试和最终完成条件，作为 Rust 小步替换的准入门禁。
+
+## 追踪记录模型
+
+每条测试方法一行，使用稳定的 `trace_id`（模块、类、方法名变更时不得复用旧语义）。必填字段如下：
+
+| 字段 | 含义 |
+|---|---|
+| `trace_id` | 唯一追踪标识 |
+| `module` / `class` / `method` | 源码位置 |
+| `capability` | API、图语义、Schema、事务、索引、存储、Raft、运维等能力域 |
+| `contract_id` | 契约登记号；没有契约不得标记 covered |
+| `test_kind` | unit、integration、e2e、property、model、fault、compatibility |
+| `execution_profile` / `ci_job` | 实际执行入口 |
+| `oracle_type` | spec、invariant、model、reference、differential |
+| `oracle_ref` | 规范、模型或代码路径的可定位引用 |
+| `independent` | Oracle 是否不依赖被测实现（yes/no/partial） |
+| `negative_case` | 是否包含错误注入或反例（yes/no） |
+| `replay` | 数据、配置、seed、故障计划是否可复现 |
+| `status` | 见下方状态机 |
+| `evidence` | CI 报告、日志、差异文件、审查记录 |
+| `reviewer` / `reviewed_at` | 非实现人员审核信息 |
+
+## 状态机
+
+`inventory` → `classified` → `contract-linked` → `oracle-linked` → `executed`
→ `reviewed` → `accepted`。任一步失败转为 `blocked`，并填写阻断原因；修复后回到失败前状态重新验证。`accepted`
不允许直接编辑，契约或实现改变时创建新版本记录。
+
+状态定义：
+
+- `inventory`：仅确认测试存在。
+- `classified`：完成能力域、测试类型和执行入口归类。
+- `contract-linked`：契约有输入、输出、错误和不变量。
+- `oracle-linked`：Oracle 可定位且证明独立性。
+- `executed`：在固定提交、配置、数据集和 seed 下实际运行。
+- `reviewed`：独立审核通过，且差异有解释。
+- `accepted`：满足迁移门禁，可作为 Rust 替换证据。
+- `blocked`：缺契约、Oracle、执行入口、复现条件或存在未解释失败。
+
+## Oracle 分层规则
+
+优先级从高到低：公开协议/标准（TinkerPop、HTTP、Protobuf）→ 数据与状态不变量 → 独立有限状态模型/属性生成器 →
经过审查的参考实现 → Java 对照差分。Java 只能发现行为差异，不能单独证明正确性。`independent=no` 的记录最高只能为
`partial`，不能进入 `accepted`。
+
+关键域最低要求：Raft 必须有线性一致性检查、崩溃/分区故障注入和快照恢复；事务必须有提交可见性不变量及并发模型测试；数据格式必须有跨版本黄金样本；API
必须有规范断言和错误响应矩阵。
+
+## 负向测试
+
+每个关键契约至少一个可重复的错误变异：删除索引更新、改变事务可见性、丢弃或重复 Raft
日志、损坏快照、篡改错误码或跳过权限校验。测试必须检测到变异并失败；否则标记 `missing-oracle`/`blocked`。变异脚本、seed
和预期失败断言纳入 `evidence`，禁止只凭代码覆盖率替代。
+
+## 最终化流程
+
+1. 解析 Maven profile、Surefire、filter 和 CI，冻结实际执行全集。
+2. 为每项能力登记版本化契约和不变量。
+3. 逐方法填充追踪字段，双人独立归类并解决分歧。
+4. 建立独立 Oracle，执行负向变异验证其杀伤力。
+5. 固定环境运行，保存报告、日志、seed、配置和数据集。
+6. 对失败进行最小化并转为确定性回归用例。
+7. 非实现人员审核后生成冻结版 CSV 和缺口清单。
+
+## 完成条件
+
+只有同时满足以下条件，测试盘点才可称为最终版并允许 Rust 单元替换：
+
+- 所有 CI 实际执行方法均达到 `reviewed` 或明确标记为 `irrelevant`；
+- 所有关键能力均有契约，且每条关键契约至少一个独立 Oracle；
+- 关键契约的负向变异测试全部被检测；
+- 无 `blocked` 项，或阻断项已登记为迁移阶段硬门禁并有负责人和截止版本；
+- 测试可在固定环境中重复，结果和差异证据已归档；
+- 追踪矩阵、契约目录、Oracle 版本和 CI 报告相互可追溯；
+- 至少一名非实现人员完成审核并签名。
+
+未满足任一条件时，只能称为“盘点底稿”，不得宣称契约兼容或测试完备。
diff --git a/docs/rust-rewrite-pd-store-test-audit.md
b/docs/rust-rewrite-pd-store-test-audit.md
new file mode 100644
index 000000000..dc5bc0fed
--- /dev/null
+++ b/docs/rust-rewrite-pd-store-test-audit.md
@@ -0,0 +1,43 @@
+# PD/Store 测试资产审计（可审查版本）
+
+## 范围与盘点结果
+
+本审计覆盖 `hugegraph-pd/hg-pd-test` 与 `hugegraph-store/hg-store-test` 的源码测试（不计
`target/` 生成物）。当前分别发现 55、64 个 `*Test.java` 文件。两者测试主要位于 `src/main/java`，因此不能仅依赖
Maven 默认 `src/test` 规则判断执行情况。
+
+PD 测试按 `core`、`raft`、`client`、`grpc`、`rest`、`common` 等 suite 组织；Store 测试按
`service` suite 及核心、业务、客户端、Raft fake-PD 场景组织。必须以 suite 配置和 Surefire XML 为实际执行证据。
+
+## 已有覆盖
+
+| 能力 | 现有证据 | 结论 |
+|---|---|---|
+| PD 分区/Store 节点服务 |
`PartitionServiceTest`、`StoreServiceTest`、`StoreNodeServiceTest` |
有单服务行为覆盖；缺少跨进程故障证据 |
+| PD Raft 基础 |
`RaftEngineReadinessTest`、`RaftEngineLeaderAddressTest`、`RaftEngineIpAuthIntegrationTest`
| 包含就绪、leader 地址及认证；未证明日志恢复和线性一致性 |
+| PD 客户端/Watch | `PDClientTest`、`PDWatchTest`、`PDPulseTest` | 有
API/回调覆盖；缺少断线重连与乱序事件模型 |
+| Store Raft 路径 | `HgSessionManager*RaftFakePDTest` | fake-PD 单节点/多 partition
场景；不等价于真实 Raft 集群 |
+| 快照 | `HgBusinessImplTest.testLoadSnapshot` 及 snapshot 相关方法 |
有加载路径；缺少生成、校验失败、增量、崩溃恢复 |
+| 分区扫描/合并 | `OrderedMultiPartitionIteratorTest`、scan 场景 | 有排序和游标测试；缺少迁移期间一致性 |
+
+## 执行入口
+
+- PD：`mvn test -pl hugegraph-pd/hg-pd-test -am`；`jacoco` 仅生成覆盖报告，不代表额外测试。
+- Store：`mvn test -pl hugegraph-store/hg-store-test -am`；`jacoco` profile 引入
RocksDB 并生成报告。
+- 最终清单必须从 Maven effective-pom、suite 类、Surefire XML 和 CI workflow
交叉确认；路径扫描结果不得作为“已执行”证明。
+
+## 关键缺口（迁移阻断）
+
+1. **Raft 正确性**：三节点选举、网络分区、消息重复/乱序、leader 崩溃、成员变更、日志截断与快照安装；用线性一致性 checker
或状态机模型作 Oracle。
+2. **持久化恢复**：提交前/后进程崩溃、磁盘重启、损坏日志、快照校验失败、旧格式读取；要求可重复故障计划和校验和。
+3. **分区生命周期**：创建/分裂/迁移/删除期间读写，副本落后追赶，leader 转移；验证数据不丢、不重、不跨分区错读。
+4. **事务语义**：并发写、可见性、重试幂等、超时后的提交状态；使用独立状态模型而非 Java 输出作为唯一真值。
+5. **升级回滚**：滚动升级、协议版本兼容、快照跨版本恢复、回滚后继续写入；保留旧版本基线。
+6. **真实集成**：fake-PD 测试需增加真实 PD/Store 多进程或容器拓扑，并纳入 CI nightly。
+
+## 补测计划与验收门禁
+
+先以一个三节点 PD + 三节点 Store 的最小拓扑做 POC：固定数据集、配置、随机 seed
和故障脚本，记录每次操作日志。随后补齐上述五类场景，每类至少包含成功、超时、崩溃和恢复用例。故意注入丢日志、跳过索引更新、错误 leader
判断等缺陷，测试必须失败（mutation score 目标 100% 针对关键不变量）。
+
+Rust 迁移单元只有在：相关测试方法已映射契约编号；Oracle 独立于 Java 实现；CI profile
可重复执行；故障与恢复场景通过；性能基线（吞吐、P99、CPU、内存）有报告；失败可回滚，才允许扩大替换范围。未满足即标记
`migration-blocked`。
+
+## 审计限制
+
+本文件是基于源码和构建配置的资产审计，不声称现有测试完备。方法级契约映射、实际 Surefire 执行结果和补测报告需在 POC
阶段提交后，才能将条目标记为 `covered`。
diff --git a/docs/rust-rewrite-server-test-audit.md
b/docs/rust-rewrite-server-test-audit.md
new file mode 100644
index 000000000..99b2ffb8e
--- /dev/null
+++ b/docs/rust-rewrite-server-test-audit.md
@@ -0,0 +1,32 @@
+# HugeGraph Server 测试资产审计
+
+## 范围与可复现基线
+
+本审计覆盖 `hugegraph-server`（含 `hugegraph-test`、各后端和 dist）。截至审计日，仓库中匹配
`*Test.java` 的测试文件为 **165** 个；该数字是资产盘点，不等于已执行覆盖。测试大量位于
`hugegraph-test/src/main/java`，必须以 Maven Surefire 报告确认实际执行。
+
+主要入口来自
`hugegraph-server/hugegraph-test/pom.xml`：`unit-test`、`core-test`、`api-test`、`tinkerpop-structure-test`、`tinkerpop-process-test`，并通过
`rocksdb`/`memory`/`hbase` backend profile 组合。CI
(`.github/workflows/server-ci.yml`) 按 backend 矩阵运行 unit、core、API、RAFT API 和
TinkerPop；`pd-store-ci.yml` 还调用 server 的脚本。`methods.filter` 与
`fast-methods.filter` 会改变实际集合，执行清单必须从 Surefire XML 生成。
+
+## 能力域盘点
+
+| 能力域 | 现有资产（代表性套件/类） | Oracle/断言现状 | 首要缺口 |
+|---|---|---|---|
+| API/REST | `ApiTestSuite`、Vertex/Edge/Schema/Manager/User/Login/Task/Metrics
API、traverser API | HTTP 状态、JSON 字段和错误断言；多为 Java 服务自测 |
OpenAPI/协议级黄金样例、错误兼容矩阵、分页/并发/超时与幂等 |
+| Gremlin/Cypher |
`GremlinApiTest`、`GremlinQueryAPITest`、`ProcessStandardTest`、`StructureStandardTest`、`CypherApiTest`
| TinkerPop 标准测试 + 结果断言 | 结果顺序/类型规范化、异常语义、长遍历资源上限、跨后端差分 |
+| Schema | PropertyKey/VertexLabel/EdgeLabel/IndexLabel/SchemaTemplate 测试及
CoreTest | 创建、更新、删除和约束断言 | 并发 schema 变更、旧版本读取、失败回滚、与索引/数据不变量关联 |
+| 索引/查询 | `IndexLabelApiTest`、`IndexLabelCoreTest`、`QueryTest`、RocksDB query
tests | 查询结果和索引状态断言 | 索引延迟/重建、崩溃恢复、覆盖率与全表扫描等价性 Oracle |
+| 事务/可见性 |
`GraphTransactionTest`、`GraphIndexTransactionTest`、Cached*TransactionTest |
提交/回滚及局部可见性 | 并发冲突、隔离级别、重试/超时、进程崩溃后的 durability |
+| 权限/认证 | `AuthTest`、`LoginApiTest`、`RolePermissionTest`、GraphSpace auth tests
| 角色和 HTTP 鉴权断言 | 权限矩阵完整性、租户隔离、token 过期/撤销、负向越权测试 |
+| 持久化/恢复 | `RestoreCoreTest`、RocksDB session/table tests、dist `InitStoreTest`
| 本地 backend 操作和恢复断言 | 跨版本格式、损坏介质、快照原子性、备份恢复及升级/回滚 |
+| 分布式/RAFT | `RoleElectionStateMachineTest`，server RAFT API 脚本 | 局部状态机/接口断言 |
三节点分区、成员变更、重复/乱序消息、线性一致性和故障注入 |
+
+## 完备性判定
+
+当前结论为“资产已收集、语义覆盖未证明”。最终矩阵必须逐测试方法记录 `contract_id`、实际 CI job/profile、Oracle
类型、可回放性、故障计划和结果。Java 实现只能用于差分，不能单独充当真值。关键契约应同时依赖公开规范、数据不变量或模型
Oracle，并以故意注入错误实现的负向测试证明测试能失败。
+
+## 补测与迁移门禁
+
+在 Rust 替换前，优先补齐：API 黄金样例与错误矩阵；事务并发/崩溃恢复；索引重建与全表等价性；旧格式和快照损坏恢复；RAFT
分区、成员变更和线性一致性；权限越权；以及所有 filter 排除项的审计。每个替换单元须先在 Java 基线固定数据、配置、seed 和 Surefire
报告，再运行 Rust 与 Java 的规范化差分、故障注入和性能基准；任一契约、恢复或性能门禁失败即停止扩大范围并回滚。
+
+## 证据产物
+
+最终审核需提交：Surefire 方法全集及未执行清单、能力—契约—Oracle 追踪矩阵、独立 Oracle 说明、负向测试报告、故障回放包、跨
backend 差分报告和性能基线。没有这些证据，不得将本审计标记为“完备”。
