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.

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)

.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

SymptomFix
build FAILCheck the repository toolchain via ./tools/cargo.sh --version, then ./tools/check.sh.
merged_chain_valid=true missingV2 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: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated 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