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 9817a7b05 docs: codify invariant driven rewrite principles
9817a7b05 is described below
commit 9817a7b0539acc44c41c4b652d92d7982f3b2454
Author: vaughn <[email protected]>
AuthorDate: Thu Sep 10 01:31:15 2026 +0800
docs: codify invariant driven rewrite principles
---
AGENTS.md | 2 ++
docs/rust-rewrite-principles.md | 30 ++++++++++++++++++++++++++++++
2 files changed, 32 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 07daf1766..cf04c7955 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,5 +104,7 @@ Before writing new tests, check existing suites under
`hugegraph-server/hugegrap
## Additional context files
+Rust 重构必须遵守
[`docs/rust-rewrite-principles.md`](docs/rust-rewrite-principles.md)：这是架构重构而非逐行翻译，必须在保持不变量的前提下重新设计并用性能和故障证据证明收益。
+
`.serena/memories/` — notably `suggested_commands.md` and
`task_completion_checklist.md`
when a task needs depth beyond this file.
diff --git a/docs/rust-rewrite-principles.md b/docs/rust-rewrite-principles.md
new file mode 100644
index 000000000..cdee1d284
--- /dev/null
+++ b/docs/rust-rewrite-principles.md
@@ -0,0 +1,30 @@
+# HugeGraph 重生式重构原则
+
+这是 HugeGraph Rust 重构的长期约束，优先级高于“尽快翻译现有代码”。
+
+## 核心判断
+
+这次工作不是 Java 到 Rust
的逐行翻译，而是在保持外部契约和关键不变量的基础上，重新设计内部架构。每个替换边界都必须回答：保留了什么不变量、删除了什么历史复杂度、性能为何会改善、失败如何恢复。
+
+## 不可妥协的原则
+
+1. **不变量优先**：协议、数据、事务、索引、Raft、快照和恢复语义先定义，再选择实现。
+2. **架构重做**：允许改变模块边界、数据结构、并发模型和执行路径；禁止为了“代码相似”复制旧缺陷。
+3. **性能有证据**：任何性能结论都必须有固定数据集、基线、profile、尾延迟、资源和长稳结果。
+4. **小步可回滚**：一次只替换一个明确边界；每一步都有双读/回放、故障验证、观察窗口和回滚开关。
+5. **成熟组件优先**：复用有真实用户和活跃维护的 Rust 组件；不自研 Raft、网络协议或底层存储，除非有正式 RFC 和充分验证。
+6. **测试不是装饰**：测试必须来自规范、不变量或独立模型，不能围绕实现结果“射箭画靶”。
+7. **代码洁癖**：减少间接层、重复状态和隐式约定；让类型表达约束，让错误可分类，让资源生命周期可见。
+8. **可观测可运营**：日志、指标、追踪、备份、升级、降级和恢复属于设计的一部分，不在最后补齐。
+
+## 每个重构单元的强制问题
+
+- 外部契约和内部不变量是什么？
+- 旧实现有哪些已知缺陷或历史包袱？本次是否有意修复？
+- 新数据结构和并发模型为什么更简单或更快？
+- 哪些结果由规范 Oracle、关系 Oracle 或模型验证？
+- 如何注入崩溃、分区、慢盘和重复消息？
+- 如何测量 P99/P999、CPU、内存、IO 和恢复时间？
+- 如何灰度、停止扩大范围并回滚？
+
+无法回答这些问题的代码只能进入实验分支，不能进入生产迁移路径。
