refactor: replace NAPI with IPC for world state, AVM, and contracts DB

.claude/skills/refactor-review/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: refactor-review
+description: Deep review of a refactor branch to catch unexpected behavioral changes, regressions, or missing functionality. Merges latest parent, resolves conflicts, then inspects the full diff.
+---
+
+# Refactor Review
+
+Deep inspection of a refactor branch to verify behavioral equivalence with the parent branch.
+
+## Purpose
+
+A refactor should change implementation without changing behavior. This review catches:
+
+- Unexpected behavioral changes (different defaults, removed features, changed error handling)
+- Regressions (tests weakened, timeouts extended, coverage removed)
+- Incomplete work (TODOs, FIXMEs, commented-out code, stub implementations)
+- Missing functionality (features on parent that aren't present on the branch)
+
+## Workflow
+
+### Step 1: Merge latest parent
+
+```bash
+# Determine the base branch
+BASE=$(gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null || echo "next")
+git fetch origin "$BASE"
+git merge "origin/$BASE"
+```
+
+If there are conflicts, resolve them and commit the merge. If conflicts are non-trivial, report them to the user before proceeding.
+
+### Step 2: Build
+
+```bash
+./bootstrap.sh
+```
+
+Fix any build errors introduced by the merge. If build errors exist pre-merge (on the branch itself), note them but don't block the review.
+
+### Step 3: Determine refactor intent
+
+If the user provided a description of the refactor's purpose, use that. Otherwise, examine:
+
+- PR title and description (`gh pr view`)
+- Commit messages (`git log origin/$BASE..HEAD --oneline`)
+- The diff itself (`git diff origin/$BASE...HEAD --stat`)
+
+Summarize the intent in one sentence before proceeding.
+
+### Step 4: Deep diff inspection
+
+Run `git diff origin/$BASE...HEAD` and analyze every change for:
+
+#### Behavioral changes
+
+- Default values changed (timeouts, pool sizes, config defaults)
+- Error handling changed (catch blocks added/removed, error types changed)
+- Control flow changed (early returns added, conditions inverted)
+- API signatures changed (parameters added/removed/reordered)
+- Feature flags or env vars added/removed/renamed
+
+#### Regressions
+
+- Test assertions weakened or removed
+- Test timeouts increased — always flag as MEDIUM with old/new values. Timeout increases can mask performance regressions; each must be justified or investigated.
+- Test cases removed or commented out
+- Error paths that now silently succeed
+- Functionality that existed on parent but is missing on the branch
+- Loss of parallelization or concurrency.
+
+#### Incomplete work
+
+- TODO/FIXME/HACK comments added
+- Stub implementations (`throw new Error('not implemented')`)
+- Commented-out code
+- Dead code paths (unreachable branches)
+
+#### Resource management
+
+- Cleanup/dispose calls removed
+- New resources without corresponding cleanup
+- Changed lifecycle (e.g., process vs thread, persistent vs per-call)
+
+### Step 5: Generate report
+
+Produce a structured report:
+
+```
+## Refactor Review: <branch-name>
+
+**Intent:** <one-sentence summary>
+**Base:** <parent branch>
+**Files changed:** <count>
+
+### Behavioral Changes
+- [file:line] Description of change and impact
+
+### Regressions
+- [file:line] Description of what was lost
+
+### Incomplete Work
+- [file:line] TODO/stub/commented-out code
+
+### Resource Management
+- [file:line] Cleanup concern
+
+### Summary
+<overall assessment: is this behaviorally equivalent?>
+```
+
+### Step 6: Wait for user
+
+Present the report and wait for the user to tell you what to fix. Do NOT make changes autonomously — the user decides which findings are intentional and which need fixing.

barretenberg/cpp/src/CMakeLists.txt

@@ -77,6 +77,9 @@ endif()
 add_subdirectory(barretenberg/api)
 add_subdirectory(barretenberg/bb)
 add_subdirectory(barretenberg/bbapi)
+add_subdirectory(barretenberg/wsdb)
+add_subdirectory(barretenberg/cdb)
+add_subdirectory(barretenberg/avm)
 add_subdirectory(barretenberg/benchmark)
 add_subdirectory(barretenberg/boomerang_value_detection)
 add_subdirectory(barretenberg/circuit_checker)

barretenberg/cpp/src/barretenberg/avm/CMakeLists.txt

@@ -0,0 +1,46 @@
+if(NOT(FUZZING) AND NOT(WASM))
+    # IPC adapter library (WsdbIpcMerkleDB + related adapters)
+    add_library(
+        avm_ipc_adapters
+        STATIC
+        wsdb_ipc_merkle_db.cpp
+    )
+    target_link_libraries(
+        avm_ipc_adapters
+        PUBLIC
+        barretenberg
+        wsdb_ipc_client
+        cdb_ipc_client
+        ipc
+    )
+
+    # aztec-avm binary (standalone AVM simulator server)
+    add_executable(
+        aztec-avm
+        main.cpp
+        cli.cpp
+        avm_execute.cpp
+        avm_ipc_server.cpp
+    )
+    target_link_libraries(
+        aztec-avm
+        PRIVATE
+        barretenberg
+        vm2_sim
+        avm_ipc_adapters
+        ipc
+        env
+    )
+    if(ENABLE_STACKTRACES)
+        target_link_libraries(
+            aztec-avm
+            PUBLIC
+            Backward::Interface
+        )
+        target_link_options(
+            aztec-avm
+            PRIVATE
+            -ldw -lelf
+        )
+    endif()
+endif()

barretenberg/cpp/src/barretenberg/avm/avm_commands.hpp

@@ -0,0 +1,68 @@
+#pragma once
+/**
+ * @file avm_commands.hpp
+ * @brief NamedUnion command structs for the aztec-avm simulation API.
+ *
+ * Commands use opaque std::vector<uint8_t> for inputs/outputs since
+ * AvmFastSimulationInputs and TxSimulationResult are large, complex types
+ * with existing msgpack serialization.
+ */
+
+#include "barretenberg/serialize/msgpack.hpp"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace bb::avm {
+
+// Forward declaration
+struct AvmRequest;
+
+// ---------------------------------------------------------------------------
+// Simulation commands
+// ---------------------------------------------------------------------------
+
+struct AvmSimulate {
+    static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmSimulate";
+    struct Response {
+        static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmSimulateResponse";
+        std::vector<uint8_t> result;
+        SERIALIZATION_FIELDS(result);
+        bool operator==(const Response&) const = default;
+    };
+    // Msgpack-serialized AvmFastSimulationInputs
+    std::vector<uint8_t> inputs;
+    SERIALIZATION_FIELDS(inputs);
+    Response execute(AvmRequest& request) &&;
+    bool operator==(const AvmSimulate&) const = default;
+};
+
+struct AvmSimulateWithHints {
+    static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmSimulateWithHints";
+    struct Response {
+        static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmSimulateWithHintsResponse";
+        std::vector<uint8_t> result;
+        SERIALIZATION_FIELDS(result);
+        bool operator==(const Response&) const = default;
+    };
+    // Msgpack-serialized AvmProvingInputs
+    std::vector<uint8_t> inputs;
+    SERIALIZATION_FIELDS(inputs);
+    Response execute(AvmRequest& request) &&;
+    bool operator==(const AvmSimulateWithHints&) const = default;
+};
+
+struct AvmShutdown {
+    static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmShutdown";
+    struct Response {
+        static constexpr const char MSGPACK_SCHEMA_NAME[] = "AvmShutdownResponse";
+        void msgpack(auto&& pack_fn) { pack_fn(); }
+        bool operator==(const Response&) const = default;
+    };
+    void msgpack(auto&& pack_fn) { pack_fn(); }
+    Response execute(AvmRequest& request) &&;
+    bool operator==(const AvmShutdown&) const = default;
+};
+
+} // namespace bb::avm