donaldfilimon/abi / .claude/skills/wdbx-roundtrip
wdbx-roundtrip
VerifiedBuild the abi CLI and drive a full WDBX persistence round-trip on a scratch segment — db init → block insert → query → db verify — proving the on-disk checkpoint + WAL chain stays valid. Use to smoke-test WDBX persistence/durability after touching the store, checkpoint, or WAL code, or to demo the block lifecycle.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.3 KB |
| roundtrip.shexecutable | script | 2.0 KB |
SKILL.md
View on GitHub---
name: wdbx-roundtrip
description: Build the abi CLI and drive a full WDBX persistence round-trip on a scratch segment — db init → block insert → query → db verify — proving the on-disk checkpoint + WAL chain stays valid. Use to smoke-test WDBX persistence/durability after touching the store, checkpoint, or WAL code, or to demo the block lifecycle.
---
> **WDBX moved out of this repository on 2026-08-22.** It now lives in the
> sibling repo `../wdbx` together with `abi-compute`,
> `abi-foundation`, `abi-core`, and `abi-telemetry`; `abi` consumes them by
> relative path. Source paths below therefore read `../wdbx/crates/...`. Run
> WDBX-only tests from that repo (`./tools/cargo.sh test --locked
> --manifest-path ../wdbx/Cargo.toml --workspace < /dev/null`, run from the abi
> checkout), and `abi`'s gate (`./tools/check.sh`) from here.
>
> Under the Abbey System Constitution
> (`docs/superpowers/specs/2026-08-22-abbey-system-constitution.md`) WDBX is the
> **provenance-aware episodic substrate**, not a vector store. Most of the
> evidence half of its specification is unimplemented; the measured gap list is
> in `docs/superpowers/specs/2026-08-22-wdbx-conformance-gap-analysis.md`. Do not
> describe an episodic capability as Current on the strength of the vector-store
> features that do exist.
# wdbx-roundtrip — drive abi's WDBX persistence lifecycle
Driver: **`.agents/skills/wdbx-roundtrip/roundtrip.sh`** (paths relative to repo root).
Builds the CLI and runs the four-step store lifecycle against a `mktemp` scratch
v2 base path (created and removed by the driver). Evidence is the `RESULT:`
line. Fully local, no network.
## Run (agent path)
```bash
.agents/skills/wdbx-roundtrip/roundtrip.sh # profile=abi, default metadata
.agents/skills/wdbx-roundtrip/roundtrip.sh aviva '{"note":"hi"}' # custom profile / metadata JSON
```
Steps and asserted markers:
1. `wdbx db init <store>` → `initialized empty WDBX v2`
2. `wdbx block insert <store> <profile> <json>` → `appended block:`, `blocks=1`
3. `wdbx query <store>` → `"blocks":1`
4. `wdbx db verify <store>` → `v2 verify OK:`, `merged_chain_valid=true`
Prints `RESULT: PASS` (exit 0) or a FAIL count.
Current Rust driver: proves v2 initialization, a UUID-backed hashed audit block,
reopen-visible stats, and successful merged audit-DAG verification.
## Gotchas
- The scratch store and activated generation live under one `mktemp` directory
and are removed on exit, so the default `.abi/` store is never opened.
- `wdbx query <store>` on a freshly-block-inserted segment reports `kv_entries:0
vectors:0 blocks:1` — blocks are the append-only content-addressed log; kv and
vectors are separate surfaces. `mode:cpu_fallback` remains honest even when
the detected backend label is `metal`.
- For semantic/vector queries (embeddings, personas) use `abi wdbx query <store>
"<text>" <persona>`; the round-trip driver checks the structural path.
- For a source-level tour of the HNSW index, MVCC snapshot chain, and WAL, use
the `wdbx-explorer` subagent.
## Troubleshooting
| Symptom | Fix |
|---|---|
| `build` FAIL | Check the repository toolchain via `./tools/cargo.sh --version`, then `./tools/check.sh`. |
| `merged_chain_valid=true` missing | V2 audit-DAG or recovery regression — inspect `../wdbx/crates/abi-wdbx/src/v2/` and `versioned.rs`. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |