Skip to content

donaldfilimon/abi / .agents/skills/wdbx-roundtrip

wdbx-roundtrip

Verified

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.

FileKindSize
SKILL.mdskill md3.3 KB
roundtrip.shexecutablescript2.0 KB
---
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`. |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall