Merge remote-tracking branch 'origin/main' into HEAD

# Conflicts:
#	src/resp/src/encode.rs
#	src/storage/src/redis_strings.rs

Author: happy-v587

.github/workflows/ci.yml

@@ -223,6 +223,10 @@ jobs:
           max_attempts: 2
           command: bash -o pipefail -c "make test 2>&1 | tee cargo-test.log"
 
+      - name: Test storage stats with fault injection
+        if: matrix.os == 'ubuntu-latest'
+        run: cargo test -p storage --features test-fault-injection --test storage_stats_test
+
       - name: Test runtime baseline tool
         run: cargo test -p runtime-baseline --all-targets
 

.planning/KANBAN.md

@@ -1,10 +1,10 @@
 # Kiwi Kanban
 
-> 更新日期：2026-07-30
+> 更新日期：2026-07-31
 >
 > 当前里程碑：M1 Redis 8.8.1 Cache OFF compatibility foundation
 >
-> 当前 task：PR `#388` implementation（`feat/rocksdb-build-accel-and-prd`）；已验证远端 Base `0f8d96238860a5c29a5582e461e4cdeb974431b3`、Head `b47cb1eebe098e2d4d2d784020dc283a8d026d28`
+> 当前 task：PR `#404` integration（远端 `codex/fix-resp-parser-limits`，本地 v4）；最新基线 `main` at `ed49ab4c3c362ba77111dbcd9791f93ebfce74a4`
 >
 > 当前运行模式：Cache OFF
 >
@@ -14,7 +14,7 @@
 
 | ID | 工作项 | Requirement / Gate 关系 | 当前状态 |
 |---|---|---|---|
-| `PR388-001` | C/C++ sccache 构建接入、跨平台回归探针、PRD/用户故事及 review 一致性修复 | `REQ-STABILITY-003`、`REQ-WORK-001`、`REQ-WORK-003`、`REQ-WORK-005`；跨平台构建修复只维护 G6 CI 的可执行性与证据条件，不构成 Gate 通过证据 | 本地针对性验证通过并形成提交；远端发布状态和新 Head CI 结果以 PR/checks/threads 实时查询为准 |
+| `RESP-LIMITS-001` | 在已合并 #406 的零声明驱动分配合同上，完成 #404 的有界 RESP 解析、未认证 buffer、parser 历史副本和 optional pipeline 背压 | `REQ-COMPAT-002`、`REQ-COMPAT-006`、`REQ-STABILITY-002`、`REQ-STABILITY-003`、`REQ-WORK-003` | #402、#403、#405、#406 已合并；v4 已解决最新 base 的 parser/pipeline 冲突，并通过 Windows/WSL 最终验证；当前发布、CI 与 review 状态从 PR #404 实时查询 |
 
 ## Ready for a separate implementation task
 
@@ -37,6 +37,7 @@
 | ID | 工作项 | Evidence | 状态 |
 |---|---|---|---|
 | `M1-001-T1` | Redis 8.8.1 exact compatibility manifest | PR `#372`；final Head `6a692bc195f96327296296977a100af301deaf01`；merge commit `9e91707d774ad367d682e23677dcef79ecb14338` | 已合并到 `main` |
+| `PR388-001` | C/C++ sccache 构建接入、跨平台回归探针、PRD/用户故事及 review 一致性修复 | PR `#388`；final Head `1ee8c916a55d03d02a250ed95af83712fa14a742`；2026-07-30 merged | 已合并到 `main` |
 
 ## Frozen unaccepted drafts
 
@@ -89,7 +90,7 @@
 
 ## WIP 与授权规则
 
-- 同一时间只允许一个 implementation card 处于 In Progress；当前为 `PR388-001`，planning/docs task 不得隐式持有 implementation card。
+- 同一时间只允许一个 implementation card 处于 In Progress；当前为 `RESP-LIMITS-001`，planning/docs task 不得隐式持有 implementation card。
 - 规划批准不授权修改 source、tests、build scripts 或 CI，也不授权 stage/commit/push 实现文件。
 - 从 planning 转 implementation 必须创建新 Codex task、TaskId、worktree、dirty allowlist 和 recovery checkpoint；不能只把 recovery mode 从 `planning` 改成 `implementation`。
 - 冻结草稿不得覆盖、续写、清理或回退；后续实施只读参考并重新审计。

.planning/STATE.md

@@ -20,15 +20,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Recovery management for degraded storage states
   - Comprehensive health monitoring and statistics
   - Backpressure handling to prevent overload
-- Architecture documentation in `docs/ARCHITECTURE.md`
+- [Architecture documentation](docs/architecture/)
 - Runtime configuration options for thread pool sizing
 - Independent health checks for network and storage runtimes
 
 ### Changed
 
 - **BREAKING CHANGE**: Default port changed from `9221` to `7379` for Redis compatibility
   - The configuration system has been migrated to Redis-style format (similar to `redis.conf`)
-  - Configuration file moved from INI format to Redis-style format at `src/conf/kiwi.conf`
+  - Configuration file moved from INI format to Redis-style format; generate it with `kiwi --sample-config > kiwi.conf` (`kiwi --full-sample-config > kiwi.conf` for all keys), then start Kiwi with `kiwi --config kiwi.conf`
   - Default port is now `7379` (a Redis-compatible variant of the standard `6379` port)
 - **BREAKING CHANGE**: Storage initialization now requires `RuntimeManager::initialize_storage_components()`
   - Must be called after `RuntimeManager::start()` and before starting storage server
@@ -50,11 +50,11 @@ If you are upgrading from a previous version that used port `9221`:
    - Old format: `config.ini` with `port=9221`
    - New format: `kiwi.conf` with `port 7379`
 
-4. **Custom port configuration**: If you need to use a different port, update the `port` setting in `src/conf/kiwi.conf`:
-   ```conf
-   # Accept connections on the specified port, default is 7379.
-   # port 7379
-   port YOUR_CUSTOM_PORT
+4. **Custom port configuration**: If you need to use a different port, redirect the generated configuration to a file, update its `port` setting, and start Kiwi with that file:
+   ```bash
+   kiwi --sample-config > kiwi.conf
+   # Edit kiwi.conf and set: port YOUR_CUSTOM_PORT
+   kiwi --config kiwi.conf
    ```
 
 5. **Docker/Container deployments**: Update any port mappings from `9221` to `7379`
@@ -102,7 +102,7 @@ If you have custom code that integrates with Kiwi:
    - `channel_buffer_size` - Message channel buffer size
    - `request_timeout` - Default request timeout
 
-See `docs/ARCHITECTURE.md` for detailed architecture documentation.
+See the [architecture documentation](docs/architecture/) for details.
 
 ### Fixed
 

CHANGELOG.md

@@ -51,7 +51,7 @@ fmt-check:
 	@cargo fmt --manifest-path ./Cargo.toml --all -- --check
 
 lint:
-	@cargo clippy --manifest-path ./Cargo.toml --all-features --workspace -- -D warnings -D clippy::unwrap_used
+	@cargo clippy --manifest-path ./Cargo.toml --all-features --workspace --all-targets -- -D warnings -D clippy::unwrap_used
 
 standalone:
 	@$(DEV) build

Makefile

@@ -78,13 +78,19 @@ the project in addition to `protoc`. See the platform-specific commands in the
 # Install rustup; rust-toolchain.toml selects Rust 1.97.1 stable in this repo
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-# protobuf compiler (macOS)
-brew install protobuf
+# macOS: Xcode CLT + protobuf compiler + CMake (required to build RocksDB from source)
+xcode-select --install
+brew install protobuf cmake
 
-# protobuf compiler (Linux)
-apt install protobuf-compiler
+# Debian/Ubuntu Linux: native C/C++ toolchain + protobuf compiler
+sudo apt install clang cmake libclang-dev llvm-dev pkg-config protobuf-compiler
 ```
 
+On Windows, use the same official Protobuf 27.1 release as CI. Download and
+extract `protoc-27.1-win64.zip`, add its `bin` directory to `PATH`, and run
+`protoc --version`. See the [development guide](docs/development.md#prerequisites)
+for the PowerShell commands.
+
 Dated nightly toolchains are reserved for specialized checks such as
 Sanitizers. They do not define the normal development or release baseline.
 
@@ -130,8 +136,13 @@ See [docs/cluster.md](docs/cluster.md) for the manual step-by-step procedure and
 | [System stability gate](docs/quality/system-stability-gate.md) | Required evidence before deferred hot-tier work can be reconsidered |
 | [Deferred native ABI contract](docs/architecture/redis-hot-tier-native-abi.md) | Future interface design; not an implementation authorization |
 | [Combined distribution licensing](docs/architecture/combined-distribution-licensing.md) | Future Redis-derived library and source-distribution obligations |
-| `kiwi --sample-config` | Generate a default config file |
-| `kiwi --full-sample-config` | Generate a config with all available keys |
+| [Product requirements (PRD)](docs/prd.md) | Goals, scope, and Redis 8.8.1 compatibility target |
+| [Engineering quality gates](docs/quality/quality-gates.md) | Code, test, and release quality gates |
+| [Personas and user stories](docs/personas-and-user-stories.md) | Target users and usage scenarios |
+| [Documentation index](docs/INDEX.md) | Map of the whole `docs/` tree and suggested reading order |
+| [Design plans & specs](docs/superpowers/) | Dated design records (plans + specs) |
+| `kiwi --sample-config > kiwi.conf` | Write the default configuration to `kiwi.conf` |
+| `kiwi --full-sample-config > kiwi.conf` | Write all available configuration keys to `kiwi.conf` |
 
 ## Dependencies
 

README.md

@@ -137,8 +137,13 @@ redis-cli -p 7379 get foo         # "bar"
 | [系统稳定性门禁](docs/quality/system-stability-gate.md) | 重新评估延期热层工作前的 required 证据 |
 | [延期的 Native ABI 合同](docs/architecture/redis-hot-tier-native-abi.md) | 未来接口设计，不构成实现授权 |
 | [组合发行许可证设计](docs/architecture/combined-distribution-licensing.md) | 未来 Redis 派生库和源码发行义务 |
-| `kiwi --sample-config` | 生成默认配置文件 |
-| `kiwi --full-sample-config` | 生成包含所有配置项的完整配置文件 |
+| [产品需求文档 (PRD)](docs/prd.md) | 目标、范围与 Redis 8.8.1 兼容基线 |
+| [工程质量门禁](docs/quality/quality-gates.md) | 代码、测试与发布质量门禁 |
+| [人物角色与用户故事](docs/personas-and-user-stories.md) | 目标用户与使用场景 |
+| [文档索引](docs/INDEX.md) | 整个 `docs/` 树的地图与建议阅读顺序 |
+| [设计计划与规格](docs/superpowers/) | 带日期的设计记录（plans + specs） |
+| `kiwi --sample-config > kiwi.conf` | 将默认配置写入 `kiwi.conf` |
+| `kiwi --full-sample-config > kiwi.conf` | 将包含所有配置项的完整配置写入 `kiwi.conf` |
 
 ## 依赖说明
 

README_CN.md

@@ -0,0 +1,75 @@
+# Documentation Index
+
+A map of the Kiwi documentation tree and a suggested reading order. If you are not
+sure where to start, follow the **Newcomer** path below.
+
+## Top-level entry points
+
+| Document | Audience | What it covers |
+|----------|----------|----------------|
+| [`README.md`](../README.md) / [`README_CN.md`](../README_CN.md) | Everyone | Project intro, features, quickstart, toolchain, and documentation entry points |
+| [`CLAUDE.md`](../CLAUDE.md) (a.k.a. `AGENTS.md`) | Contributors / AI agents | Dev commands, crate layout, code style, behavioral guidelines |
+| [`CONTRIBUTING.md`](../CONTRIBUTING.md) | Contributors | How to contribute |
+| [`CHANGELOG.md`](../CHANGELOG.md) | Everyone | Notable changes (history) |
+
+## Planning & requirements (source of truth for roadmap)
+
+The `.planning/` directory holds the north star, requirements, milestones, current
+state, and Kanban. These files are referenced from the README and the PRD and are
+the authoritative tracking surface:
+
+- `.planning/PROJECT.md` — constitution / north star
+- `.planning/REQUIREMENTS.md` — acceptance requirements (`REQ-*`)
+- `.planning/ROADMAP.md` — milestones (`M0`–`M10`)
+- `.planning/STATE.md` — current state
+- `.planning/KANBAN.md` — work board
+- `.planning/DECISIONS.md` / `.planning/OPEN_QUESTIONS.md` / `.planning/REFERENCES.md`
+
+## Developer docs
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/development.md`](development.md) | Dev environment, build optimization, sccache, lint rules, testing (incl. Python integration) |
+| [`docs/cluster.md`](cluster.md) | Raft cluster quickstart and write-path verification |
+| [`docs/key-encoding.md`](key-encoding.md) | Key/value encoding internals (Chinese, with diagrams) |
+
+## Product & compatibility
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/prd.md`](prd.md) | Product requirements; goals, scope, Redis 8.8.1 compatibility target |
+| [`docs/personas-and-user-stories.md`](personas-and-user-stories.md) | Target users and usage scenarios |
+| [`docs/compatibility/redis-8.8.1.md`](compatibility/redis-8.8.1.md) | Exact Oracle, raw RESP, TCL, and client-test boundaries |
+| [`docs/compatibility/redisraft-public-profile.md`](compatibility/redisraft-public-profile.md) | RedisRaft public compatibility profile |
+
+## Architecture
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/architecture/redis-8.8.1-system-boundaries.md`](architecture/redis-8.8.1-system-boundaries.md) | Cache OFF request, storage, and consensus boundaries |
+| [`docs/architecture/redis-hot-tier-native-abi.md`](architecture/redis-hot-tier-native-abi.md) | Deferred native ABI contract (future design, not an implementation authorization) |
+| [`docs/architecture/combined-distribution-licensing.md`](architecture/combined-distribution-licensing.md) | Future Redis-derived library and source-distribution licensing obligations |
+
+## Quality & stability
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/quality/system-stability-gate.md`](quality/system-stability-gate.md) | Required evidence (G1–G7) before deferred hot-tier work is reconsidered |
+| [`docs/quality/quality-gates.md`](quality/quality-gates.md) | Code, test, and release quality gates |
+| [`docs/performance/storage-runtime-baseline.md`](performance/storage-runtime-baseline.md) | Storage-runtime performance baseline |
+
+## Design history (`docs/superpowers/`)
+
+`docs/superpowers/plans/` and `docs/superpowers/specs/` contain **dated design
+records** (filename prefix `YYYY-MM-DD-`). They are historical decision logs, not
+a second roadmap. Follow related specs and plans by topic and by their explicit
+cross-references; dates do not define a one-to-one pairing. For the current
+authoritative plan, prefer `.planning/ROADMAP.md` and the gate documents above.
+
+## Suggested reading order
+
+- **Newcomer**: `README.md` → `docs/development.md` → `docs/cluster.md` → `docs/key-encoding.md`
+- **Contributor**: `CLAUDE.md` → `docs/development.md` → `docs/quality/quality-gates.md`
+- **Architecture / compatibility**: `docs/prd.md` → `docs/compatibility/redis-8.8.1.md` → `docs/architecture/redis-8.8.1-system-boundaries.md`
+- **Stability & quality**: `docs/quality/system-stability-gate.md` → `docs/quality/quality-gates.md` → `docs/performance/storage-runtime-baseline.md`
+- **Design history**: `docs/superpowers/plans/` + `docs/superpowers/specs/` (follow by topic and explicit cross-references)

docs/INDEX.md

@@ -172,17 +172,24 @@ cargo test --package storage      # tests for a specific crate
 cargo test test_redis_mset        # run a single test by name
 ```
 
-Python integration tests require a running Kiwi server:
+The Python integration runner starts an isolated Kiwi server on `127.0.0.1:6379`,
+runs the test suite against it, and stops the server afterward:
 
 ```bash
-# Terminal 1
-cargo run --bin kiwi
+# Build the debug binary used by the runner and install the test dependencies
+cargo build --bin kiwi
+make -C tests install-deps
 
-# Terminal 2
-pip install redis pytest
-pytest tests/python/ -v
+# Start the isolated server and run the Python integration suite
+./tests/run_python_integration.sh
 ```
 
+`make -C tests install-deps` installs the version-constrained dependencies from
+`tests/python/requirements.txt`. The runner sets `KIWI_TEST_REQUIRE_SERVER=1` and
+`KIWI_TEST_ISOLATED_SERVER=1` so tests cannot silently pass by skipping server-
+dependent cases. See [tests/README.md](../tests/README.md) and
+[tests/NEW_TESTS_GUIDE.md](../tests/NEW_TESTS_GUIDE.md) for details.
+
 Storage tests use `tempfile::tempdir()` for isolated RocksDB instances.
 
 ## Gotchas

docs/development.md

@@ -7,13 +7,13 @@
 ## String 结构的存储
 
 
-![img.png](images/01-string编码.png)
+![String 编码结构](images/01-string编码.png)
 
 ## Hash 结构的存储
 
 Hash 类型数据结构由两部分构成，元数据（meta_key，meta_value）和普通数据（data_key，data_value）。每个 Hash 类型数据对应一条元数据，每个 field 对应一条普通数据。具体格式如下图所示。
 
-![img.png](images/01-hash编码.png)
+![Hash 编码结构](images/01-hash编码.png)
 
 元数据中的 key 由前缀保留字段，编码后的 user key 以及后缀保留字段构成，value 中记录了 hash 中元素个数，最新版本号，保留字段，数据写入时间以及数据过期时间。version 字段使用 u64 little-endian 编码，并用于实现秒删功能。
 
@@ -29,13 +29,13 @@ Hash 类型数据结构由两部分构成，元数据（meta_key，meta_value）
 
 set 结构与 hash 类型的存储格式基本相同，也是由元数据和普通数据两部分构成。不同的是，set 类型由于没有 value字段，所以其 data value 中只需要记录保留字段和数据写入时间即可。具体格式如下所示：
 
-![img.png](images/01-set编码.png)
+![Set 编码结构](images/01-set编码.png)
 
 ## List 结构的存储
 
 list 由两部分构成，元数据(meta_key, meta_value), 和普通数据(data_key, data_value)。 元数据中存储的主要是 list 链表的一些信息， 比如说当前 list 链表结点的的数量以及当前 list 链表的版本号和过期时间(用做秒删功能), 还有当前 list 链表的左右边界, 普通数据实际上就是指的 list 中每一个结点中的数据，作为具体最后 RocksDB 落盘的 KV 格式，具体格式如下所示：
 
-![img.png](images/01-list编码.png)
+![List 编码结构](images/01-list编码.png)
 
 元数据中记录了一个 list 的信息，包括 list 元素个数，左右边界 Index，最新 version以及数据写入时间和过期时间。普通数据的 key 拼接了 list key 和 Index，value 记录用户写入数据以及写入时间。
 
@@ -47,7 +47,7 @@ list 由两部分构成，元数据(meta_key, meta_value), 和普通数据(data_
 
 zset 由两部分构成，元数据(meta_key, meta_value) 和普通数据(data_key, data_value)。元数据中存储的主要是 zset 集合的一些信息，比如当前 zset 集合中 member 的数量以及当前 zset 集合的版本号和过期时间（用于秒删功能），而普通数据就是指 zset 中每个 member 以及对应的 score。由于 zset 这种数据结构比较特殊，需要按照 member 排序，也需要按照 score 排序，所以我们会按不同格式存储两份普通数据，在这里称为 member to score 和 score to member。作为最终 RocksDB 落盘的 KV 格式，具体如下：
 
-![img.png](images/01-zset编码.png)
+![ZSet 编码结构](images/01-zset编码.png)
 
 Meta KV 记录的是一个 zset 的元信息，包括集合元素个数，最新版本号，数据写入时间以及数据过期时间。对 zset 类型数据的读写删除操作都需要先获取元数据。