docs: update compat_fuse README to match current implementation

Author: dantengsky

tests/compat_fuse/README.md

@@ -1,35 +1,68 @@
 # Fuse table compatibility test
 
-This script tests whether a newer version databend-query can read fuse table data written
-by a older version databend-query.
+Tests write-then-read compatibility of fuse-table format across databend-query versions.
+
+- **Backward compat**: old writer → current reader
+- **Forward compat**: current writer → old reader
+
+## Test matrix
+
+All test cases are defined in `test_cases.yaml`. Each entry specifies:
+
+| Field    | Description                                                        |
+|----------|--------------------------------------------------------------------|
+| `writer` | Query version that writes data (`"current"` = latest build)       |
+| `reader` | Query version that reads data (`"current"` = latest build)        |
+| `meta`   | Meta-service versions to run in order (upgrades on-disk meta data) |
+| `suite`  | sqllogictest sub-directory under `compat-logictest/`               |
+
+To add a test case, append an entry to `test_cases.yaml`.
 
 ## Usage
 
+Run all cases (CI mode):
+
 ```shell
-python3 tests/compat_fuse/test_compat_fuse.py --writer-version <old_ver> --reader-version current --meta-versions <meta_ver>
-tests/compat_fuse/test_compat_fuse_forward.sh <old_ver>
+python3 tests/compat_fuse/test_compat_fuse.py --run-all
 ```
 
-E.g. `tests/compat_fuse/test-compat_fuse.sh 0.7.151` tests if the fuse-table written
-by **databend-query-0.7.151** can be read by **current** version databend-query.
+Dry run (print cases without executing):
 
-`tests/compat_fuse/test-fuse-forward-compat.sh 1.2.307` tests if the fuse-table written
-by **current** can be read by **databend-query-0.7.151** version databend-query.
+```shell
+python3 tests/compat_fuse/test_compat_fuse.py --run-all --dry-run
+```
+
+Run a single case (local debugging):
+
+```shell
+python3 tests/compat_fuse/test_compat_fuse.py \
+    --writer-version 1.2.46 \
+    --reader-version current \
+    --meta-versions 1.2.527 1.2.677 1.2.833 \
+    --logictest-path base
+```
 
 ## Prerequisites
 
-- Current version of databend-query and databend-meta must reside in `./bins`:
-    - `./bins/current/databend-query`
-    - `./bins/current/databend-meta`
+Current version binaries must reside in `./bins/current/bin/`:
+
+- `databend-query`
+- `databend-meta`
+- `databend-sqllogictests`
+
+This is handled by the CI setup action. Old version binaries are downloaded automatically.
+
+## Test flow
 
-    Since building a binary takes several minutes,
-    this step is usually done by the calling process, e.g., the CI script.
+For each case, the script runs three phases:
 
+1. **Write** — start meta (first version) + query (writer version), run `fuse_compat_write`
+2. **Meta upgrade** — cycle through all meta versions to upgrade on-disk data
+3. **Read** — start meta (last version) + query (reader version), run `fuse_compat_read`
 
 ## Testing data
 
-- Suite `tests/compat_fuse/compat-logictest/fuse_compat_write` writes data into a fuse table via an old version query.
-- Suite `tests/compat_fuse/compat-logictest/fuse_compat_read` reads the data via current version query.
+Each suite under `compat-logictest/` contains two sqllogictest files:
 
-Fuse table maintainers update these two `logictest` scripts to let the write/read
-operations cover fuse-table features.
+- `fuse_compat_write` — creates tables and writes data
+- `fuse_compat_read` — reads and verifies the data