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 f22a2d663 docs(tools): add linearizability report example
f22a2d663 is described below
commit f22a2d6633269540ac7a2ad89038f639ae0f4c79
Author: vaughn <[email protected]>
AuthorDate: Sun Sep 13 15:26:10 2026 +0800
docs(tools): add linearizability report example
---
tools/raft-linearizability/README.md | 6 ++++++
tools/raft-linearizability/examples/three-node-sample.json | 12 ++++++++++++
tools/raft-linearizability/test_checker.py | 10 ++++++++++
3 files changed, 28 insertions(+)
diff --git a/tools/raft-linearizability/README.md
b/tools/raft-linearizability/README.md
index cde68a4c1..2034115dc 100644
--- a/tools/raft-linearizability/README.md
+++ b/tools/raft-linearizability/README.md
@@ -15,3 +15,9 @@ python3 tools/raft-linearizability/checker.py history.json
Exit status is zero when linearizable and one otherwise. The JSON output
contains a witness operation order or an explanation.
+
+For collected three-node histories, keep a stable report envelope containing
+`metadata.commit`, `metadata.config`, `metadata.seed`, the operation array in
+`history`, and the checker output in `checker`. A ready-to-copy example is
+`examples/three-node-sample.json`; the checker itself remains independent of
+any service or cluster.
diff --git a/tools/raft-linearizability/examples/three-node-sample.json
b/tools/raft-linearizability/examples/three-node-sample.json
new file mode 100644
index 000000000..2eea6b36e
--- /dev/null
+++ b/tools/raft-linearizability/examples/three-node-sample.json
@@ -0,0 +1,12 @@
+{
+ "metadata": {
+ "commit": "deadbeef",
+ "config": "three-node-local",
+ "seed": 42
+ },
+ "history": [
+ {"id": "w1", "op": "write", "value": 7, "start": 0, "end": 4},
+ {"id": "r1", "op": "read", "value": 7, "start": 2, "end": 5}
+ ],
+ "checker": {"linearizable": true, "detail": ["w1", "r1"]}
+}
diff --git a/tools/raft-linearizability/test_checker.py
b/tools/raft-linearizability/test_checker.py
index 8dc40edeb..70344b4fc 100644
--- a/tools/raft-linearizability/test_checker.py
+++ b/tools/raft-linearizability/test_checker.py
@@ -1,4 +1,5 @@
import importlib.util
+import json
from pathlib import Path
spec = importlib.util.spec_from_file_location("checker",
Path(__file__).with_name("checker.py"))
@@ -36,6 +37,15 @@ def test_overlapping_writes_and_reads_are_not_linearizable():
assert not checker.check(h)[0]
+def test_three_node_report_example_has_metadata_and_result():
+ path = Path(__file__).parent / "examples" / "three-node-sample.json"
+ report = json.loads(path.read_text())
+ assert {"commit", "config", "seed"} <= report["metadata"].keys()
+ ok, detail = checker.check(report["history"])
+ assert report["checker"]["linearizable"] == ok
+ assert report["checker"]["detail"] == list(detail)
+
+
def test_invalid_operation_is_rejected():
ok, detail = checker.check([{"id": 1, "op": "delete", "value": 0,
"start": 0, "end": 1}])
