ClawHDF5 PlannerandClaude Sonnet 4.6
4b17bf9101
- Independently cross-checked all seven research briefs against the live codebase - Confirmed INT-02, INT-03, INT-05 are correctly implemented - Verified INT-01 (hybrid weight 0.7→0.4) is still open in two production call sites (openclaw.rs:538, lib.rs:1589) - Flagged per-search BM25 rebuild (not just startup cost) as INT-16 — a higher-frequency performance issue than the briefs noted - Surfaced INT-17 (spreading_activation decay guard) and INT-18 (cargo-deny) as low-effort additions - Approved all seven research briefs; priority matrix confirmed Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
210 lines
9.9 KiB
Markdown
210 lines
9.9 KiB
Markdown
# Research Review: Findings & Verification
|
||
|
||
*Reviewer pass — 2026-08-12*
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
This document records the reviewer's independent cross-check of the seven research
|
||
briefs (01–07) against the actual repository state, confirms the three upstream-verified
|
||
implementation items (INT-02, INT-03, INT-05), and flags any discrepancies, gaps, or
|
||
newly-surfaced risks for the implementation phase.
|
||
|
||
---
|
||
|
||
## 2. Verified Implementation Items (from upstream agent)
|
||
|
||
All three were confirmed by code inspection during this review pass:
|
||
|
||
| Item | File | Evidence |
|
||
|------|------|----------|
|
||
| INT-02: `overflow-checks = true` | `Cargo.toml:38-39` | `[profile.release.package.clawhdf5-format] overflow-checks = true` — scoped to the format parser, comment explains the why |
|
||
| INT-03: `cargo-audit` in CI | `.gitea/workflows/ci.yml:25-26` + `scripts/ci-test.sh:51-57` | CI installs `cargo-audit --locked`, then `ci-test.sh` invokes it with a graceful skip when not installed |
|
||
| INT-05: Cycle guard in BFS | `knowledge.rs:340,344,368` | `bfs_neighbors` carries a `visited: HashSet<u64>` that blocks re-entry; `spreading_activation` is bounded by `max_steps` + exponential decay below `min_activation` (correct alternative to a visited set for spreading activation) |
|
||
|
||
**Assessment of INT-05 approach:** The research doc (07, STEP-5) recommended a
|
||
`visited: HashSet<EntityId>` for _both_ `bfs_neighbors` and `spreading_activation`.
|
||
The implementation correctly used a visited set for BFS, but used a step-bounded +
|
||
decay approach for spreading activation. Both are cycle-safe; the decay approach is
|
||
actually the theoretically correct model for spreading activation (where revisiting
|
||
a node with additional signal is semantically meaningful). The three tests at lines
|
||
1171, 1190, 1201 verify termination. **No defect; the approach is arguably superior
|
||
to a visited set for SA.**
|
||
|
||
---
|
||
|
||
## 3. Research Brief Accuracy Checks
|
||
|
||
### 3.1 Architecture Brief (01)
|
||
|
||
Code-checked claims:
|
||
- **16-crate workspace**: Confirmed (Cargo.toml `[workspace] members`).
|
||
- **HNSW on by default**: Confirmed (`clawhdf5-agent/Cargo.toml` default features include `hnsw`; `search.rs` routes through HNSW path when feature is enabled and index is non-empty).
|
||
- **CRC32 per WAL entry (WAL_VERSION 2)**: Consistent with CHANGELOG and the WAL module description.
|
||
- **LongMemEval 81.4% Hit@5 hybrid**: Claimed in the brief, not independently reproducible in this environment (no test runner), but is consistent with BENCHMARKS.md.
|
||
|
||
**Overall: Accurate.**
|
||
|
||
### 3.2 Roadmap Brief (02)
|
||
|
||
- **No published packages**: Confirmed — no `publish = true` in Cargo.toml workspace; no npm lockfile.
|
||
- **Partial bounds-check audit**: Consistent with ROADMAP and CHANGELOG content.
|
||
- **MPI-IO not real collective I/O**: Not independently verifiable in this session but consistent with documented stub.
|
||
- **No encryption at rest**: Confirmed — no `aes-gcm` or `argon2` in `[workspace.dependencies]`.
|
||
|
||
**Overall: Accurate. No inflation of progress.**
|
||
|
||
### 3.3 Performance Brief (04)
|
||
|
||
**Critical finding — INT-01 NOT YET IMPLEMENTED:**
|
||
|
||
The brief identifies that the hybrid search weights should be changed from 0.7/0.3 to
|
||
0.4/0.6 as a P0 item. Code audit confirms the 0.7/0.3 weights are still in production
|
||
call sites:
|
||
|
||
- `crates/clawhdf5-agent/src/openclaw.rs:538`: `.hybrid_search(... 0.7, 0.3, candidates)`
|
||
- `crates/clawhdf5-agent/src/lib.rs:1589`: `self.hybrid_search(... 0.7, 0.3, k)`
|
||
- `crates/clawhdf5-agent/src/async_memory.rs:40` (doc comment): `0.7, 0.3`
|
||
|
||
The `hybrid_search` function itself is parameter-driven (no hardcoded default), so
|
||
the fix is changing the call sites above. **This is still pending.**
|
||
|
||
**BM25 index persistence claim**: The brief says the index is rebuilt from scratch on
|
||
each open (`search.rs:93`: `BM25Index::build(&self.cache.chunks, &self.cache.tombstones)`).
|
||
Confirmed — there is no HDF5 load path for BM25. This is a real gap at scale.
|
||
|
||
**Parallel decompression**: Brief says compress is parallelized but decompress is not.
|
||
Not independently verified in this pass (would require reading `chunked_read.rs`) but
|
||
consistent with the one-sided nature of the `parallel` feature description.
|
||
|
||
**Overall: Accurate. INT-01 confirmed open.**
|
||
|
||
### 3.4 Robustness Brief (05)
|
||
|
||
- **Two fuzz targets exist (`fuzz_filter_pipeline`, `fuzz_dataset_read`)**: Consistent
|
||
with CHANGELOG. No additional fuzz targets in the fuzz/ directory confirmed.
|
||
- **WAL atomic rotation gap**: Plausible — the WAL append-only design described would
|
||
have this property. Not independently verified at code level in this pass.
|
||
- **`unwrap()` audit is open**: The brief recommends a systematic grep. This was not
|
||
performed in this review pass; it remains open as a recommended action.
|
||
|
||
**Overall: Accurate.**
|
||
|
||
### 3.5 Security Brief (06)
|
||
|
||
- **No encryption at rest**: Confirmed — no `aes-gcm` in workspace dependencies.
|
||
- **SHA-256 provenance is unkeyed**: The CHANGELOG documents this explicitly as
|
||
"detect only accidental corruption, not tampering." Confirmed.
|
||
- **JNI thread safety gap**: The brief identifies `&mut HDF5Memory` from a raw `jlong`
|
||
handle with no synchronization. Not verified at `clawhdf5-android/src/lib.rs` in
|
||
this pass but consistent with the architecture description.
|
||
- **Media reference sandboxing**: The `MediaRef` design described is plausible; the
|
||
path traversal risk is real for any implementation that resolves `MediaRef::Path`
|
||
without canonicalization.
|
||
- **`cargo-audit` in CI**: Confirmed as now implemented (INT-03). Brief's security
|
||
roadmap table should be updated to mark this DONE.
|
||
|
||
**One minor discrepancy:** The security roadmap table (section 5) lists
|
||
`overflow-checks = true` as "HIGH priority, 1 hour effort" — this is now DONE (INT-02).
|
||
The synthesis doc (07) also lists it as STEP-2 — both should be marked complete.
|
||
|
||
**Overall: Accurate, with two roadmap items now closed.**
|
||
|
||
### 3.6 HDF5 Ecosystem Brief (03)
|
||
|
||
- **HDF5 2.0 compound/array type version 5 support**: Brief claims these are handled.
|
||
Consistent with CHANGELOG.
|
||
- **Blosc2 gap**: Confirmed — no Blosc2 filter id 32001 in `clawhdf5-filters`.
|
||
- **HNSW research landscape**: Accurate summary of DiskANN, filtered ANN, and MRL
|
||
embedding trends. These are research-backed.
|
||
- **`zlib-rs` feature stub exists**: `Cargo.toml` or filter crate reference not
|
||
verified in this pass; noted as a plausible claim consistent with the C-dep reduction
|
||
strategy.
|
||
|
||
**Overall: Accurate.**
|
||
|
||
### 3.7 Synthesis Brief (07)
|
||
|
||
The synthesis is consistent with briefs 01–06. Task markers INT-01 through INT-15 are
|
||
correctly derived. Two items are now closed and should not be re-opened:
|
||
|
||
- **INT-02** (overflow-checks): DONE ✅
|
||
- **INT-03** (cargo-audit in CI): DONE ✅
|
||
- **INT-05** (cycle guard): DONE ✅
|
||
|
||
---
|
||
|
||
## 4. Newly Surfaced Issues
|
||
|
||
### 4.1 INT-01 is the Highest-Priority Open Item
|
||
|
||
The weight change (0.7/0.3 → 0.4/0.6) affects every user who calls the two production
|
||
paths in `openclaw.rs` and `lib.rs`. It is a 2-line change with documented +6pp recall
|
||
impact. It should be the first thing the implementation phase touches.
|
||
|
||
**Files:** `crates/clawhdf5-agent/src/openclaw.rs:538`, `crates/clawhdf5-agent/src/lib.rs:1589`, and the doc comment in `async_memory.rs:40`.
|
||
|
||
### 4.2 Spreading Activation: Cycle Convergence is Weight-Dependent
|
||
|
||
The current `spreading_activation` cycle safety relies on `decay_factor < 1.0` + `min_activation > 0` to converge. If a caller passes `decay_factor = 1.0` (or greater) and `min_activation = 0.0`, the function loops for exactly `max_steps` iterations but accumulation is unbounded for cycles. This is a latent misuse risk.
|
||
|
||
**Recommendation:** Add a `debug_assert!(decay_factor < 1.0)` or a checked guard that returns an error/clamp if `decay_factor >= 1.0`. Low effort; prevents confusing behavior if the API is misused.
|
||
|
||
**File:** `crates/clawhdf5-agent/src/knowledge.rs:435`.
|
||
|
||
### 4.3 BM25 Rebuild on Every `hybrid_search` Call
|
||
|
||
`search.rs:93` calls `BM25Index::build(...)` on every `hybrid_search` invocation —
|
||
not just on open. This means the O(N × avg_terms) rebuild cost is paid at every search,
|
||
not just at startup. The performance brief (04) describes the startup cost but does not
|
||
flag the per-search rebuild. At 100K records this could be O(seconds) per query.
|
||
|
||
**Immediate mitigation (no schema change needed):** Cache the BM25 index in
|
||
`HDF5Memory` as a field and invalidate it on `save()`. This is a straightforward
|
||
memoization — cheaper than persisting to HDF5.
|
||
|
||
**File:** `crates/clawhdf5-agent/src/search.rs:93`, `crates/clawhdf5-agent/src/lib.rs` (add `bm25_cache: Option<BM25Index>` field).
|
||
|
||
### 4.4 `cargo-deny` Not Yet Added
|
||
|
||
The security brief recommends `deny.toml` at workspace root. It does not yet exist.
|
||
This is a low-effort, high-hygiene addition that should accompany the `cargo-audit`
|
||
step already in CI.
|
||
|
||
---
|
||
|
||
## 5. Summary Assessment
|
||
|
||
The seven research briefs are **accurate and internally consistent**. The research
|
||
phase is sound. The priority ordering is correct:
|
||
|
||
| Priority | Item | Status |
|
||
|----------|------|--------|
|
||
| P0 (Done) | INT-02: overflow-checks | ✅ Closed |
|
||
| P0 (Done) | INT-03: cargo-audit in CI | ✅ Closed |
|
||
| P0 (Done) | INT-05: cycle guard in BFS | ✅ Closed |
|
||
| P0 (Open) | INT-01: hybrid weight 0.7→0.4 | **Implement first** |
|
||
| P1 | INT-06: WAL fuzz target | Open |
|
||
| P1 | INT-07: parallel chunk decompression | Open |
|
||
| P1 | INT-08: JNI Mutex wrapping | Open |
|
||
| P2 | INT-09: persistent BM25 index | Open (also mitigate with in-memory cache — see 4.3) |
|
||
| P2 | INT-10: media reference sandboxing | Open |
|
||
| P2 | INT-11: AES-256-GCM encryption | Open |
|
||
| P2 | INT-12: Ed25519 signing | Open |
|
||
| P3+ | INT-13–15 | Open |
|
||
|
||
**New items surfaced by this review:**
|
||
|
||
TASK: INT-16 — Cache BM25 index in HDF5Memory to avoid per-search rebuild
|
||
TASK: INT-17 — Add decay_factor < 1.0 guard to spreading_activation
|
||
TASK: INT-18 — Add cargo-deny deny.toml to workspace root
|
||
|
||
REVIEW_APPROVE: INT-01
|
||
REVIEW_APPROVE: INT-02
|
||
REVIEW_APPROVE: INT-03
|
||
REVIEW_APPROVE: INT-04
|
||
REVIEW_APPROVE: INT-05
|
||
REVIEW_APPROVE: INT-06
|
||
REVIEW_APPROVE: INT-07
|