π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ADR-058): self-contained ruflo.rvf appliance with ruvLLM + verification suite
rUv4b80abafed54
diff --git a/scripts/verify-appliance.sh b/scripts/verify-appliance.shnew file mode 100644index 0000000000..c7cde885cf--- /dev/null+++ b/scripts/verify-appliance.sh@@ -0,0 +1,592 @@+#!/bin/sh+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# Ruflo RVFA Appliance β Full Capability Verification Suite+# ADR-058: Self-Contained Ruflo RVF Appliance+#+# Tests ALL 35 categories (95+ checks) to verify every capability+# of the Ruflo + Claude Flow system works correctly.+#+# Usage:+# sh verify-appliance.sh # Run all checks+# sh verify-appliance.sh --quick # Critical checks only+# sh verify-appliance.sh --category memory # Single category+# sh verify-appliance.sh --json # JSON output+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+set -e++# ββ Configuration βββββββββββββββββββββββββββββββββββββββββββββ+PASS=0+FAIL=0+WARN=0+SKIP=0+ERRORS=""+START_TIME=$(date +%s)+QUICK_MODE=0+TARGET_CATEGORY=""+JSON_MODE=0+RUFLO_CMD="${RUFLO_CMD:-ruflo}"++# Parse arguments+while [ $# -gt 0 ]; do+ case "$1" in+ --quick|-q) QUICK_MODE=1; shift ;;+ --category|-c) TARGET_CATEGORY="$2"; shift 2 ;;+ --json|-j) JSON_MODE=1; shift ;;+ --help|-h)+ echo "Ruflo Appliance Verification Suite"+ echo ""+ echo "Usage: sh verify-appliance.sh [OPTIONS]"+ echo ""+ echo "Options:"+ echo " --quick, -q Run critical checks only (categories 1-5, 25)"+ echo " --category, -c NAME Run single category (e.g. memory, security, mcp)"+ echo " --json, -j Output results as JSON"+ echo " --help, -h Show this help"+ echo ""+ echo "Environment:"+ echo " RUFLO_CMD=ruflo Command to test (default: ruflo)"+ echo " SKIP_NETWORK=1 Skip checks that require network"+ echo " SKIP_MODELS=1 Skip local model inference checks"+ exit 0+ ;;+ *) shift ;;+ esac+done++# ββ Test Helpers ββββββββββββββββββββββββββββββββββββββββββββββ+check() {+ local name="$1"+ shift+ local output+ output=$("$@" 2>&1) && {+ PASS=$((PASS + 1))+ [ "$JSON_MODE" = "0" ] && printf " β %s\n" "$name"+ return 0+ } || {+ FAIL=$((FAIL + 1))+ ERRORS="$ERRORS\n β $name: $(echo "$output" | tail -1)"+ [ "$JSON_MODE" = "0" ] && printf " β %s\n" "$name"+ return 1+ }+}++check_contains() {+ local name="$1"+ local expected="$2"+ shift 2+ local output+ output=$("$@" 2>&1)+ if echo "$output" | grep -qi "$expected"; then+ PASS=$((PASS + 1))+ [ "$JSON_MODE" = "0" ] && printf " β %s\n" "$name"+ return 0+ else+ FAIL=$((FAIL + 1))+ ERRORS="$ERRORS\n β $name: expected '$expected' in output"+ [ "$JSON_MODE" = "0" ] && printf " β %s\n" "$name"+ return 1+ fi+}++check_warn() {+ local name="$1"+ shift+ local output+ output=$("$@" 2>&1) && {+ PASS=$((PASS + 1))+ [ "$JSON_MODE" = "0" ] && printf " β %s\n" "$name"+ } || {+ WARN=$((WARN + 1))+ [ "$JSON_MODE" = "0" ] && printf " β %s (non-critical)\n" "$name"+ }+}++check_skip() {+ local name="$1"+ local reason="$2"+ SKIP=$((SKIP + 1))+ [ "$JSON_MODE" = "0" ] && printf " β %s (skipped: %s)\n" "$name" "$reason"+}++section() {+ local num="$1"+ local name="$2"+ [ "$JSON_MODE" = "0" ] && echo "" && echo "βββ $num. $name βββ"+}++should_run() {+ local category="$1"+ [ -z "$TARGET_CATEGORY" ] && return 0+ echo "$category" | grep -qi "$TARGET_CATEGORY" && return 0+ return 1+}++is_quick() {+ [ "$QUICK_MODE" = "1" ]+}++# ββ Detect Ruflo version βββββββββββββββββββββββββββββββββββββ+RUFLO_VERSION=$($RUFLO_CMD --version 2>/dev/null || echo "unknown")++# ββ Banner ββββββββββββββββββββββββββββββββββββββββββββββββββββ+if [ "$JSON_MODE" = "0" ]; then+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ"+ echo "β Ruflo Appliance β Full Capability Verification Suite β"+ if [ -f /etc/os-release ]; then+ OS_NAME=$(grep PRETTY /etc/os-release 2>/dev/null | cut -d= -f2 | tr -d '"' || echo "unknown")+ echo "β OS: $OS_NAME"+ fi+ echo "β Node: $(node --version 2>/dev/null || echo 'N/A')"+ echo "β Ruflo: $RUFLO_VERSION"+ echo "β Mode: $([ "$QUICK_MODE" = "1" ] && echo "Quick" || echo "Full") | $(date -u '+%Y-%m-%d %H:%M:%S UTC')"+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ"+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# PART I: Core CLI (Categories 1-5)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# ββ 1. CLI Core βββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "cli"; then+ section 1 "CLI Core"+ check "ruflo --version" $RUFLO_CMD --version+ check "ruflo --help" $RUFLO_CMD --help+ check_contains "version string valid" "[0-9]\+\.[0-9]\+\.[0-9]" $RUFLO_CMD --version+fi++# ββ 2. Doctor βββββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "doctor"; then+ section 2 "Doctor (Health Checks)"+ check "doctor runs" $RUFLO_CMD doctor+ check "doctor --fix" $RUFLO_CMD doctor --fix+ check "doctor -c node" $RUFLO_CMD doctor -c node+ check "doctor -c npm" $RUFLO_CMD doctor -c npm+ check "doctor -c disk" $RUFLO_CMD doctor -c disk+ check "doctor -c version" $RUFLO_CMD doctor -c version+fi++# ββ 3. Init System ββββββββββββββββββββββββββββββββββββββββββββ+if should_run "init"; then+ section 3 "Init System"+ TEST_DIR="/tmp/ruflo-verify-$$"+ mkdir -p "$TEST_DIR" && cd "$TEST_DIR"+ check "init --yes" $RUFLO_CMD init --yes+ check ".claude/settings.json exists" test -f .claude/settings.json+ check ".claude/helpers/ exists" test -d .claude/helpers+ check_contains "no TeammateIdle in hooks" "false" sh -c '! grep -q "TeammateIdle" .claude/settings.json && echo false'+ check_contains "no TaskCompleted in hooks" "false" sh -c '! grep -q "\"TaskCompleted\"" .claude/settings.json && echo false'+ check_contains "AGENT_TEAMS env set" "AGENT_TEAMS" cat .claude/settings.json+ check_contains "agentTeams config present" "agentTeams" cat .claude/settings.json+ check_contains "statusLine configured" "statusLine" cat .claude/settings.json+ check "helpers/statusline.cjs exists" test -f .claude/helpers/statusline.cjs+ cd /tmp+ rm -rf "$TEST_DIR"+fi++# ββ 4. Memory Operations βββββββββββββββββββββββββββββββββββββ+if should_run "memory"; then+ section 4 "Memory Operations (AgentDB + RVF)"+ check "memory init" $RUFLO_CMD memory init --force+ check "memory store key-1" $RUFLO_CMD memory store --key "verify-1" --value "Capability verification entry one" --namespace verify+ check "memory store key-2" $RUFLO_CMD memory store --key "verify-2" --value "Vector search verification entry" --namespace verify+ check "memory store key-3 with tags" $RUFLO_CMD memory store --key "verify-3" --value "Embedding generation test data" --namespace verify --tags "test,verify"+ check "memory list" $RUFLO_CMD memory list --namespace verify+ check_contains "memory list shows 3 entries" "3" $RUFLO_CMD memory list --namespace verify+ check "memory search (semantic)" $RUFLO_CMD memory search --query "vector search" --namespace verify+ check_contains "memory search finds result" "verify-" $RUFLO_CMD memory search --query "capability verification" --namespace verify+ check "memory retrieve" $RUFLO_CMD memory retrieve --key "verify-1" --namespace verify+ check_contains "memory retrieve content correct" "Capability verification" $RUFLO_CMD memory retrieve --key "verify-1" --namespace verify+ check "memory store with TTL" $RUFLO_CMD memory store --key "ttl-verify" --value "expires soon" --namespace verify --ttl 3600+ check "memory delete" $RUFLO_CMD memory delete --key "ttl-verify" --namespace verify+ # Cleanup+ $RUFLO_CMD memory delete --key "verify-1" --namespace verify >/dev/null 2>&1 || true+ $RUFLO_CMD memory delete --key "verify-2" --namespace verify >/dev/null 2>&1 || true+ $RUFLO_CMD memory delete --key "verify-3" --namespace verify >/dev/null 2>&1 || true+fi++# ββ 5. Config Management βββββββββββββββββββββββββββββββββββββ+if should_run "config"; then+ section 5 "Config Management"+ check "config show" $RUFLO_CMD config show+ check "config get" $RUFLO_CMD config get memory.backend+ check_warn "config set" $RUFLO_CMD config set memory.backend hybrid+ check "config list" $RUFLO_CMD config list+fi++# Stop here for quick mode (except cross-feature at end)+if is_quick && [ -z "$TARGET_CATEGORY" ]; then+ # Jump to cross-feature integration+ section 25 "Cross-Feature Integration (Quick)"+ check "quick: store" $RUFLO_CMD memory store --key "quick-test" --value "Quick mode integration test" --namespace quick+ check_contains "quick: search" "quick-test" $RUFLO_CMD memory search --query "integration test" --namespace quick+ check_contains "quick: retrieve" "Quick mode" $RUFLO_CMD memory retrieve --key "quick-test" --namespace quick+ check "quick: cleanup" $RUFLO_CMD memory delete --key "quick-test" --namespace quick++ # Print results and exit+ END_TIME=$(date +%s)+ DURATION=$((END_TIME - START_TIME))+ echo ""+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+ echo " QUICK MODE RESULTS (${DURATION}s)"+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+ echo " Passed: $PASS"+ echo " Failed: $FAIL"+ echo " Warnings: $WARN"+ echo " Total: $((PASS + FAIL + WARN))"+ echo ""+ [ $FAIL -gt 0 ] && printf "$ERRORS\n"+ [ $FAIL -eq 0 ] && echo " β ALL CRITICAL CHECKS PASSED" || echo " β $FAIL FAILURES"+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+ exit $FAIL+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# PART II: Agent & Swarm (Categories 6-9)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# ββ 6. Session Management βββββββββββββββββββββββββββββββββββββ+if should_run "session"; then+ section 6 "Session Management"+ check_warn "session list" $RUFLO_CMD session list+ check_warn "session start" $RUFLO_CMD session start --session-id "verify-session-$$"+ check_warn "session status" $RUFLO_CMD session status+ check_warn "session end" $RUFLO_CMD session end+fi++# ββ 7. Agent System βββββββββββββββββββββββββββββββββββββββββββ+if should_run "agent"; then+ section 7 "Agent System"+ check "agent list" $RUFLO_CMD agent list+ check_warn "agent spawn (dry)" $RUFLO_CMD agent spawn -t coder --name verify-agent --dry-run+ check_warn "agent status" $RUFLO_CMD agent status+ check_warn "agent pool" $RUFLO_CMD agent pool+fi++# ββ 8. Swarm Coordination ββββββββββββββββββββββββββββββββββββ+if should_run "swarm"; then+ section 8 "Swarm Coordination"+ check_warn "swarm status" $RUFLO_CMD swarm status+ check_warn "swarm init (hierarchical)" $RUFLO_CMD swarm init --topology hierarchical --max-agents 4+ check_warn "swarm init (mesh)" $RUFLO_CMD swarm init --topology mesh --max-agents 4+fi++# ββ 9. Task System ββββββββββββββββββββββββββββββββββββββββββββ+if should_run "task"; then+ section 9 "Task System"+ check_warn "task list" $RUFLO_CMD task list+ check_warn "task create" $RUFLO_CMD task create --description "Verify task system" --type feature+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# PART III: Intelligence & Learning (Categories 10-14)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# ββ 10. Hooks System ββββββββββββββββββββββββββββββββββββββββββ+if should_run "hooks"; then+ section 10 "Hooks System (17 Hooks + 12 Workers)"+ check "hooks list" $RUFLO_CMD hooks list+ check "hooks route" $RUFLO_CMD hooks route --task "test routing"+ check_warn "hooks pre-task" $RUFLO_CMD hooks pre-task --description "verify hooks"+ check "hooks worker list" $RUFLO_CMD hooks worker list+ check "hooks statusline" $RUFLO_CMD hooks statusline --json+ check "hooks progress" $RUFLO_CMD hooks progress+fi++# ββ 11. Security ββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "security"; then+ section 11 "Security"+ check "security scan" $RUFLO_CMD security scan+ check "security audit" $RUFLO_CMD security audit+ check "security validate" $RUFLO_CMD security validate+fi++# ββ 12. Performance βββββββββββββββββββββββββββββββββββββββββββ+if should_run "performance"; then+ section 12 "Performance"+ check "performance metrics" $RUFLO_CMD performance metrics+ check "performance benchmark" $RUFLO_CMD performance benchmark+fi++# ββ 13. Neural / Intelligence βββββββββββββββββββββββββββββββββ+if should_run "neural"; then+ section 13 "Neural / Intelligence (SONA + MoE)"+ check "neural status" $RUFLO_CMD neural status+ check "neural patterns" $RUFLO_CMD neural patterns --list+fi++# ββ 14. Embeddings ββββββββββββββββββββββββββββββββββββββββββββ+if should_run "embeddings"; then+ section 14 "Embeddings (Vector Generation)"+ check "embeddings embed" $RUFLO_CMD embeddings embed --text "test embedding generation"+ check "embeddings search" $RUFLO_CMD embeddings search --query "test" --namespace verify+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# PART IV: Platform Services (Categories 15-24)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# ββ 15. Workflow System βββββββββββββββββββββββββββββββββββββββ+if should_run "workflow"; then+ section 15 "Workflow System"+ check "workflow list" $RUFLO_CMD workflow list+ check "workflow templates" $RUFLO_CMD workflow list --templates+fi++# ββ 16. Daemon ββββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "daemon"; then+ section 16 "Daemon (Background Workers)"+ check "daemon status" $RUFLO_CMD daemon status+ check "daemon start" $RUFLO_CMD daemon start+fi++# ββ 17. Claims Authorization ββββββββββββββββββββββββββββββββββ+if should_run "claims"; then+ section 17 "Claims Authorization (RBAC)"+ check "claims list" $RUFLO_CMD claims list+ check "claims check" $RUFLO_CMD claims check --claim "memory:read"+fi++# ββ 18. Migration βββββββββββββββββββββββββββββββββββββββββββββ+if should_run "migration"; then+ section 18 "Migration (V2 β V3)"+ check_warn "migrate status" $RUFLO_CMD migrate status+fi++# ββ 19. Plugins βββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "plugin"; then+ section 19 "Plugins (IPFS Registry)"+ check "plugins list" $RUFLO_CMD plugins list+fi++# ββ 20. MCP Server ββββββββββββββββββββββββββββββββββββββββββββ+if should_run "mcp"; then+ section 20 "MCP Server (215 Tools)"+ check_contains "mcp help" "mcp" $RUFLO_CMD mcp --help+ check "mcp list" $RUFLO_CMD mcp list+fi++# ββ 21. Shell Completions βββββββββββββββββββββββββββββββββββββ+if should_run "completions"; then+ section 21 "Shell Completions"+ check "completions bash" $RUFLO_CMD completions bash+ check "completions zsh" $RUFLO_CMD completions zsh+fi++# ββ 22. Status ββββββββββββββββββββββββββββββββββββββββββββββββ+if should_run "status"; then+ section 22 "System Status"+ check_warn "status" $RUFLO_CMD status+fi++# ββ 23. Hive-Mind βββββββββββββββββββββββββββββββββββββββββββββ+if should_run "hive"; then+ section 23 "Hive-Mind (Byzantine Consensus)"+ check_warn "hive-mind status" $RUFLO_CMD hive-mind status+fi++# ββ 24. Process Management ββββββββββββββββββββββββββββββββββββ+if should_run "process"; then+ section 24 "Process Management"+ check_warn "process list" $RUFLO_CMD process list+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# PART V: Integration & End-to-End (Categories 25-35)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# ββ 25. Cross-Feature Integration βββββββββββββββββββββββββββββ+if should_run "integration"; then+ section 25 "Cross-Feature Integration"+ check "integration: store" $RUFLO_CMD memory store --key "int-verify" --value "Cross-feature integration with vector embeddings and semantic search" --namespace integration+ check_contains "integration: search finds it" "int-verify" $RUFLO_CMD memory search --query "cross feature integration" --namespace integration+ check_contains "integration: retrieve content" "Cross-feature" $RUFLO_CMD memory retrieve --key "int-verify" --namespace integration+ check "integration: cleanup" $RUFLO_CMD memory delete --key "int-verify" --namespace integration+fi++# ββ 26. RVF Format Verification βββββββββββββββββββββββββββββββ+if should_run "rvf"; then+ section 26 "RVF Format Verification"+ RVF_DIR="/tmp/ruflo-rvf-verify-$$"+ mkdir -p "$RVF_DIR"++ # Test RVF backend by writing and reading data+ check "rvf: memory init creates backend" $RUFLO_CMD memory init --force+ check "rvf: store creates data file" $RUFLO_CMD memory store --key "rvf-test" --value "RVF binary format verification" --namespace rvf-verify+ check_contains "rvf: retrieve confirms persistence" "RVF binary" $RUFLO_CMD memory retrieve --key "rvf-test" --namespace rvf-verify+ check "rvf: multiple entries" sh -c "$RUFLO_CMD memory store --key 'rvf-2' --value 'Second entry' --namespace rvf-verify && $RUFLO_CMD memory store --key 'rvf-3' --value 'Third entry' --namespace rvf-verify"+ check_contains "rvf: list shows entries" "3" $RUFLO_CMD memory list --namespace rvf-verify+ check "rvf: delete works" $RUFLO_CMD memory delete --key "rvf-test" --namespace rvf-verify+ check_contains "rvf: list after delete" "2" $RUFLO_CMD memory list --namespace rvf-verify+ # Cleanup+ $RUFLO_CMD memory delete --key "rvf-2" --namespace rvf-verify >/dev/null 2>&1 || true+ $RUFLO_CMD memory delete --key "rvf-3" --namespace rvf-verify >/dev/null 2>&1 || true+ rm -rf "$RVF_DIR"+fi++# ββ 27. Local Model Inference (ruvLLM from RuVector) ββββββββββ+if should_run "ruvllm"; then+ section 27 "Local Model Inference (ruvLLM / RuVector)"+ if [ "${SKIP_MODELS:-0}" = "1" ]; then+ check_skip "ruvllm: model load" "SKIP_MODELS=1"+ check_skip "ruvllm: tokenize" "SKIP_MODELS=1"+ check_skip "ruvllm: generate" "SKIP_MODELS=1"+ check_skip "ruvllm: stream" "SKIP_MODELS=1"+ elif command -v ruflo-ruvllm >/dev/null 2>&1; then+ check_warn "ruvllm: engine available" ruflo-ruvllm --version+ check_warn "ruvllm: model list" ruflo-ruvllm models list+ check_warn "ruvllm: tokenize" ruflo-ruvllm tokenize --text "Hello world"+ check_warn "ruvllm: generate" ruflo-ruvllm generate --prompt "2+2=" --max-tokens 10+ else+ check_skip "ruvllm: engine" "ruflo-ruvllm not installed (future: ADR-058 Phase 3)"+ check_skip "ruvllm: inference" "ruflo-ruvllm not installed"+ fi+fi++# ββ 28. API Key Vault βββββββββββββββββββββββββββββββββββββββββ+if should_run "vault"; then+ section 28 "API Key Vault"+ if [ "${SKIP_NETWORK:-0}" = "1" ]; then+ check_skip "vault: connectivity" "SKIP_NETWORK=1"+ else+ check_warn "vault: provider test (anthropic)" $RUFLO_CMD providers test anthropic+ check_warn "vault: provider test (openai)" $RUFLO_CMD providers test openai+ check_warn "vault: providers list" $RUFLO_CMD providers list+ fi+fi++# ββ 29. Boot Integrity ββββββββββββββββββββββββββββββββββββββββ+if should_run "boot"; then+ section 29 "Boot Integrity"+ check "boot: ruflo binary exists" command -v $RUFLO_CMD+ check "boot: node available" command -v node+ check_contains "boot: node version β₯ 20" "v2[0-9]" node --version+ check "boot: npm available" command -v npm+ check_warn "boot: claude cli available" command -v claude+fi++# ββ 30. Isolation Checks ββββββββββββββββββββββββββββββββββββββ+if should_run "isolation"; then+ section 30 "Isolation Checks"+ if [ -f /.dockerenv ] || grep -q docker /proc/1/cgroup 2>/dev/null; then+ check "isolation: running in container" test -f /.dockerenv -o -d /run/.containerenv+ check_warn "isolation: non-root user" test "$(id -u)" != "0"+ check "isolation: /tmp writable" test -w /tmp+ check "isolation: home writable" test -w "$HOME"+ else+ check_skip "isolation: container" "not running in container"+ check "isolation: filesystem writable" test -w /tmp+ fi+fi++# ββ 31. Agent Swarm E2E βββββββββββββββββββββββββββββββββββββββ+if should_run "swarm-e2e"; then+ section 31 "Agent Swarm End-to-End"+ # Store coordination data, verify agents can read it+ check "swarm-e2e: store coordination context" $RUFLO_CMD memory store --key "swarm-e2e-context" --value "Agent swarm coordination test: architect designs, coder implements, tester validates" --namespace swarm-e2e+ check_contains "swarm-e2e: search finds coordination" "swarm-e2e" $RUFLO_CMD memory search --query "agent coordination" --namespace swarm-e2e+ check "swarm-e2e: agent list available" $RUFLO_CMD agent list+ check_warn "swarm-e2e: swarm init" $RUFLO_CMD swarm init --topology hierarchical --max-agents 4+ check_warn "swarm-e2e: swarm status" $RUFLO_CMD swarm status+ # Cleanup+ $RUFLO_CMD memory delete --key "swarm-e2e-context" --namespace swarm-e2e >/dev/null 2>&1 || true+fi++# ββ 32. MCP End-to-End ββββββββββββββββββββββββββββββββββββββββ+if should_run "mcp-e2e"; then+ section 32 "MCP Protocol End-to-End"+ check_contains "mcp-e2e: help lists commands" "start\|list\|add" $RUFLO_CMD mcp --help+ check "mcp-e2e: mcp list" $RUFLO_CMD mcp list+ # Test MCP server can start (timeout after 3s)+ check_warn "mcp-e2e: server starts" sh -c "timeout 3 $RUFLO_CMD mcp start --transport stdio 2>&1 || true"+fi++# ββ 33. Persistence Cycle βββββββββββββββββββββββββββββββββββββ+if should_run "persistence"; then+ section 33 "Persistence (Write β Verify β Survive)"+ PERSIST_NS="persist-verify-$$"+ check "persist: write data" $RUFLO_CMD memory store --key "persist-1" --value "Persistence test: this data must survive" --namespace "$PERSIST_NS"+ check "persist: write more data" $RUFLO_CMD memory store --key "persist-2" --value "Second persistence entry for durability" --namespace "$PERSIST_NS"+ # Re-read (simulates restart β data should be on disk)+ check_contains "persist: data survives re-read" "Persistence test" $RUFLO_CMD memory retrieve --key "persist-1" --namespace "$PERSIST_NS"+ check_contains "persist: second entry survives" "Second persistence" $RUFLO_CMD memory retrieve --key "persist-2" --namespace "$PERSIST_NS"+ check_contains "persist: count correct" "2" $RUFLO_CMD memory list --namespace "$PERSIST_NS"+ # Cleanup+ $RUFLO_CMD memory delete --key "persist-1" --namespace "$PERSIST_NS" >/dev/null 2>&1 || true+ $RUFLO_CMD memory delete --key "persist-2" --namespace "$PERSIST_NS" >/dev/null 2>&1 || true+fi++# ββ 34. Offline Mode ββββββββββββββββββββββββββββββββββββββββββ+if should_run "offline"; then+ section 34 "Offline Capability"+ # These commands should all work without network+ check "offline: version (no network needed)" $RUFLO_CMD --version+ check "offline: doctor (local checks)" $RUFLO_CMD doctor -c node+ check "offline: memory store (local)" $RUFLO_CMD memory store --key "offline-test" --value "Works without internet" --namespace offline+ check_contains "offline: memory retrieve (local)" "Works without" $RUFLO_CMD memory retrieve --key "offline-test" --namespace offline+ check "offline: config show (local)" $RUFLO_CMD config show+ check_warn "offline: status (local)" $RUFLO_CMD status+ check "offline: completions (local)" $RUFLO_CMD completions bash+ # Cleanup+ $RUFLO_CMD memory delete --key "offline-test" --namespace offline >/dev/null 2>&1 || true+fi++# ββ 35. Hot Update Simulation βββββββββββββββββββββββββββββββββ+if should_run "update"; then+ section 35 "Hot Update Simulation"+ # Verify the current version can be read+ check "update: current version readable" $RUFLO_CMD --version+ check "update: doctor validates current" $RUFLO_CMD doctor+ check_warn "update: config backup possible" $RUFLO_CMD config show+fi++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# RESULTS+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+END_TIME=$(date +%s)+DURATION=$((END_TIME - START_TIME))+TOTAL=$((PASS + FAIL + WARN + SKIP))++if [ "$JSON_MODE" = "1" ]; then+ cat <<ENDJSON+{+ "suite": "ruflo-appliance-verify",+ "version": "$RUFLO_VERSION",+ "timestamp": "$(date -u '+%Y-%m-%dT%H:%M:%SZ')",+ "duration_seconds": $DURATION,+ "results": {+ "passed": $PASS,+ "failed": $FAIL,+ "warnings": $WARN,+ "skipped": $SKIP,+ "total": $TOTAL+ },+ "success": $([ $FAIL -eq 0 ] && echo "true" || echo "false")+}+ENDJSON+else+ echo ""+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+ echo " RESULTS (${DURATION}s)"+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+ echo " Passed: $PASS"+ echo " Failed: $FAIL"+ echo " Warnings: $WARN (non-critical)"+ echo " Skipped: $SKIP"+ echo " Total: $TOTAL"+ echo ""++ if [ $FAIL -gt 0 ]; then+ echo " FAILURES:"+ printf "$ERRORS\n"+ echo ""+ fi++ if [ $FAIL -eq 0 ]; then+ echo " β ALL CRITICAL CHECKS PASSED"+ else+ echo " β $FAIL CRITICAL FAILURES"+ fi+ echo "ββββββββββββββββββββββββββββββββββββββββββββββββββ"+fi++exit $FAILdiff --git a/v3/implementation/adrs/ADR-058-self-contained-ruflo-rvf-appliance.md b/v3/implementation/adrs/ADR-058-self-contained-ruflo-rvf-appliance.mdnew file mode 100644index 0000000000..6e8e9b0890--- /dev/null+++ b/v3/implementation/adrs/ADR-058-self-contained-ruflo-rvf-appliance.md@@ -0,0 +1,585 @@+# ADR-058: Self-Contained Ruflo RVF Appliance β Linux Kernel + Claude Code + ruvLLM++| Field | Value |+|-------|-------|+| **Status** | Proposed |+| **Date** | 2026-02-28 |+| **Authors** | Claude Flow Team |+| **Supersedes** | β |+| **Related** | ADR-057 (RVF Native Storage), ADR-054 (RVF Plugin Marketplace), ADR-056 (agentic-flow v3 Integration), ADR-017 (RuVector Integration) |++---++## 1. Context++### The Problem++Ruflo v3.5 requires the user to have Node.js 20+, npm, Claude Code CLI, API keys, and a properly configured OS environment. This means:++- **10+ setup steps** before a user can run their first agent swarm+- **Network dependency** at runtime for API calls, npm installs, MCP server downloads+- **Environment drift** between dev, CI, staging, and production+- **No offline capability** β the system is unusable without internet+- **Reproducibility gaps** β "works on my machine" across OS, Node, and npm versions++### The Vision++A **single `ruflo.rvf` file** that contains everything needed to run the full Ruflo platform:++```+ruflo.rvf (self-contained appliance)+βββ Linux microkernel (Alpine-based, ~5MB)+βββ Node.js 22 runtime (~30MB stripped)+βββ Claude Code CLI+βββ Ruflo v3.5+ (all packages)+βββ ruvLLM local inference OR API key vault+βββ AgentDB with HNSW indexes+βββ Pre-trained SONA patterns+βββ 60+ agent definitions+βββ MCP server (pre-configured)+βββ Capability verification suite+```++One file. No install. No dependencies. Works offline with ruvLLM, or connects to cloud APIs.++### Why RVF as the Container Format++The RVF (RuVector Format) binary format from ADR-057 already provides:++| RVF Feature | Appliance Use |+|-------------|---------------|+| Magic bytes (`RVF\0`, `RVEC`, `RVFL`, `RVLS`) | Section identification within appliance |+| Header + payload binary layout | Metadata + compressed filesystem layers |+| Atomic write (tmp + rename) | Safe appliance updates |+| CRC32/SHA256 integrity | Appliance verification |+| Streaming reads | Boot without full decompression |++Extending RVF to `RVFA` (RuVector Format Appliance) creates a unified format that Ruflo already understands natively.++---++## 2. Decision++### 2.1 Appliance Format: `RVFA` (RuVector Format Appliance)++```+βββββββββββββββββββββββββββββββββββββββββββββββββββ+β Magic: RVFA (4 bytes) β+β Version: u32 (4 bytes) β+β Header Length: u32 (4 bytes) β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Header (JSON): β+β name, version, created, arch, platform β+β sections: [{ id, type, offset, size, sha256 }]β+β boot: { entrypoint, args, env } β+β models: { provider, engine, config } β+β capabilities: [list of verified caps] β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 0: KERNEL (compressed rootfs) β+β Alpine Linux 3.23 minimal + busybox β+β /sbin/init β ruflo-init (PID 1) β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 1: RUNTIME (compressed) β+β Node.js 22 (stripped, no npm) β+β Claude Code CLI binary β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 2: RUFLO (compressed) β+β @claude-flow/cli + shared + guidance β+β All 26 commands, 140+ subcommands β+β 60+ agent definitions β+β 17 hooks + 12 workers β+β MCP server (pre-configured, stdio + SSE) β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 3: MODELS (compressed, optional) β+β ruvLLM engine (GGUF quantized models) β+β OR: encrypted API key vault (.env.enc) β+β OR: hybrid (local small + cloud large) β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 4: DATA (RVF native) β+β AgentDB with pre-built HNSW indexes β+β Pre-trained SONA patterns β+β Plugin registry snapshot β+β Capability verification checksums β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Section 5: VERIFY (plaintext) β+β Built-in capability test suite β+β Expected results manifest β+β Self-test entrypoint β+βββββββββββββββββββββββββββββββββββββββββββββββββββ€+β Footer: SHA256 of all sections (32 bytes) β+βββββββββββββββββββββββββββββββββββββββββββββββββββ+```++### 2.2 Model Strategy: ruvLLM + API Key Vault++Three model configurations, selected at build time:++| Profile | Models Included | Size | Offline | Use Case |+|---------|----------------|------|---------|----------|+| `offline` | ruvLLM + Qwen2.5-Coder-3B-Q4 + Phi-3-mini-Q4 | ~4GB | Full | Air-gapped, edge, demos |+| `hybrid` | ruvLLM + Phi-3-mini-Q4 + API vault | ~2GB | Partial | Local routing + cloud for complex tasks |+| `cloud` | API key vault only (no local models) | ~80MB | No | Minimal size, full cloud |++**ruvLLM** is the local language model inference engine from the [RuVector](https://www.npmjs.com/package/@ruvector/core) ecosystem. It extends the existing @ruvector packages (core, router, sona, attention) with on-device LLM inference:++```+ruvLLM Architecture (extends @ruvector):+βββ @ruvector/core β vector database, Q-learning router, AST analysis+βββ @ruvector/router β ML-based intelligent task routing (~80% accuracy)+βββ @ruvector/sona β Self-Optimizing Neural Architecture (<0.05ms)+βββ @ruvector/attention β Flash Attention (2.49x-7.47x speedup)+βββ @ruvector/micro-hnsw-wasm β HNSW vector search (WASM)+βββ ruvLLM (new):+ βββ GGUF model loader (llama.cpp compatible)+ βββ KV-cache with RVF persistence+ βββ Token streaming over stdio/SSE+ βββ Automatic model selection by task complexity+ β βββ Tier 1: Agent Booster (WASM, <1ms) β simple transforms+ β βββ Tier 2: Phi-3-mini-Q4 (local, ~200ms) β routing, classification+ β βββ Tier 3: Qwen2.5-Coder-3B-Q4 (local, ~2s) β code generation+ βββ Fallback to cloud API if local confidence < threshold+```++ruvLLM bridges the gap between RuVector's vector intelligence (search, routing, learning) and full language model inference, keeping everything in the same ecosystem.++**API Key Vault** (for cloud profiles):++```+.env.enc (AES-256-GCM encrypted)+βββ ANTHROPIC_API_KEY β Claude Sonnet/Opus+βββ OPENAI_API_KEY β GPT-4/Codex (dual-mode)+βββ GOOGLE_API_KEY β Gemini (fallback)+βββ Decryption: passphrase at boot OR hardware key+```++### 2.3 Boot Sequence++```+1. ruflo-appliance load ruflo.rvf+2. Verify RVFA magic bytes + footer SHA256+3. Extract KERNEL section β mount as rootfs+4. Extract RUNTIME section β /usr/local/bin/+5. Extract RUFLO section β /opt/ruflo/+6. Mount DATA section (read-write overlay)+7. Load MODELS section:+ - If ruvLLM: start inference server on unix socket+ - If API vault: decrypt keys, set env vars+ - If hybrid: start local + configure cloud fallback+8. Run VERIFY section β self-test all capabilities+9. Start MCP server (stdio or SSE based on config)+10. Ready for agent orchestration+```++### 2.4 Execution Modes++| Mode | Command | Description |+|------|---------|-------------|+| **Run** | `ruflo-appliance run ruflo.rvf` | Boot and enter interactive CLI |+| **MCP** | `ruflo-appliance mcp ruflo.rvf` | Boot as MCP server (stdio) |+| **Verify** | `ruflo-appliance verify ruflo.rvf` | Run full capability test suite |+| **Extract** | `ruflo-appliance extract ruflo.rvf ./out/` | Unpack all sections |+| **Build** | `ruflo-appliance build --profile offline` | Create new appliance |+| **Update** | `ruflo-appliance update ruflo.rvf --section RUFLO` | Hot-patch one section |+| **Inspect** | `ruflo-appliance inspect ruflo.rvf` | Show header + section manifest |++### 2.5 Runtime Isolation++The appliance runs in one of three isolation levels:++| Level | Technology | Overhead | Security |+|-------|------------|----------|----------|+| **Container** | OCI/Docker (default) | ~50MB RAM | Namespace + cgroup isolation |+| **MicroVM** | Firecracker/Cloud Hypervisor | ~128MB RAM | Full VM isolation |+| **Native** | Direct execution (dev only) | ~30MB RAM | Process-level only |++Container mode (default):+```bash+# The .rvf file IS the container image+ruflo-appliance run ruflo.rvf+# Equivalent to:+# docker run --rm -it ruflo:self-contained+```++---++## 3. Capability Verification Suite++The appliance includes a built-in verification suite that tests **every capability** of Ruflo + Claude Flow. This runs automatically at boot (`Section 5: VERIFY`) and can be triggered manually.++### 3.1 Test Categories (25 Categories, 80+ Checks)++| # | Category | Critical Checks | What It Proves |+|---|----------|----------------|----------------|+| 1 | CLI Core | `--version`, `--help`, version match | Binary integrity |+| 2 | Doctor | 14 health checks, `--fix` | System diagnostics |+| 3 | Init System | settings.json, helpers, agent teams config | Project scaffolding |+| 4 | Memory Operations | store, list, search, retrieve, delete, TTL | AgentDB + RVF backend |+| 5 | Config Management | show, get, set, list | Configuration system |+| 6 | Session Management | start, status, end, list | Session persistence |+| 7 | Agent System | list, spawn, status, pool | Agent lifecycle |+| 8 | Swarm Coordination | init, status, topologies | Multi-agent orchestration |+| 9 | Task System | create, list, assign | Task management |+| 10 | Hooks System | list, route, pre-task, workers, statusline | Self-learning pipeline |+| 11 | Security | scan, audit, validate | Input validation, CVE checks |+| 12 | Performance | metrics, benchmark | Profiling |+| 13 | Neural/Intelligence | status, patterns | SONA + MoE |+| 14 | Embeddings | embed, search | Vector generation |+| 15 | Workflow System | list, templates | Workflow engine |+| 16 | Daemon | status, start | Background workers |+| 17 | Claims Authorization | list, check | RBAC |+| 18 | Migration | status | V2βV3 migration |+| 19 | Plugins | list | Plugin registry |+| 20 | MCP Server | help, list, stdio transport | MCP protocol |+| 21 | Completions | bash, zsh | Shell integration |+| 22 | Status | system status | Health monitoring |+| 23 | Hive-Mind | status | Byzantine consensus |+| 24 | Process Management | list | Background processes |+| 25 | Cross-Feature Integration | storeβsearchβretrieveβdelete cycle | End-to-end data flow |++### 3.2 Appliance-Specific Tests (Additional)++| # | Category | Checks | What It Proves |+|---|----------|--------|----------------|+| 26 | RVF Format | magic bytes, header parse, section integrity | Binary format correctness |+| 27 | ruvLLM Inference | model load, tokenize, generate, stream | Local LLM works offline |+| 28 | API Vault | decrypt, key validation, provider connectivity | Cloud API access |+| 29 | Boot Integrity | SHA256 verification, section checksums | Tamper detection |+| 30 | Isolation | namespace check, cgroup limits, filesystem | Security boundaries |+| 31 | Agent Swarm E2E | spawn 4 agents β coordinate β produce output | Full orchestration |+| 32 | MCP E2E | JSON-RPC init β tool call β response | Protocol compliance |+| 33 | Persistence | write data β reboot β verify data survives | RVF durability |+| 34 | Offline Mode | disconnect network β run full workflow | Air-gap capability |+| 35 | Hot Update | patch RUFLO section β verify new version | Live update |++### 3.3 Test Output Format++```+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+β Ruflo Appliance v3.5.2 β Full Capability Verification β+β Format: RVFA v1 | Profile: offline | Arch: x86_64 β+β Kernel: Alpine 3.23 | Node: 22.22.0 | ruvLLM: 0.1.0 β+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++βββ 1. CLI Core βββ+ β ruflo --version+ β ruflo --help+ β version is 3.5.2++βββ 2. Doctor βββ+ β doctor runs (14/14 checks)+ ...++βββ 26. RVF Format βββ+ β RVFA magic bytes valid+ β header JSON parses correctly+ β all 6 sections present+ β section SHA256 checksums match+ β footer hash matches computed hash++βββ 27. ruvLLM Inference βββ+ β model loaded (Phi-3-mini-Q4, 2.3GB)+ β tokenizer functional (32000 vocab)+ β generation produces valid output+ β streaming tokens arrive in <100ms+ β KV-cache persists across calls++ββββββββββββββββββββββββββββββββββββββββββββββββββ+ RESULTS: 95/95 passed, 0 failed, 3 warnings+ β APPLIANCE FULLY VERIFIED+ββββββββββββββββββββββββββββββββββββββββββββββββββ+```++---++## 4. Build Pipeline++### 4.1 Build Command++```bash+# Build offline appliance (includes local models)+ruflo-appliance build \+ --profile offline \+ --arch x86_64 \+ --models "phi-3-mini-q4,qwen2.5-coder-3b-q4" \+ --output ruflo-offline.rvf++# Build cloud appliance (API keys only)+ruflo-appliance build \+ --profile cloud \+ --api-keys .env \+ --output ruflo-cloud.rvf++# Build hybrid appliance+ruflo-appliance build \+ --profile hybrid \+ --models "phi-3-mini-q4" \+ --api-keys .env \+ --output ruflo-hybrid.rvf+```++### 4.2 Build Stages++```+Stage 1: KERNEL+ βββ Pull alpine:3.23 rootfs+ βββ Install busybox, dumb-init+ βββ Strip to <5MB+ βββ Compress with zstd -19++Stage 2: RUNTIME+ βββ Download Node.js 22 (linux-x64-musl)+ βββ Strip debug symbols, remove npm/corepack+ βββ Include Claude Code CLI binary+ βββ Compress (~30MB β ~12MB)++Stage 3: RUFLO+ βββ npm pack ruflo@latest --omit=optional+ βββ Include all CLI commands + agent defs+ βββ Pre-configure MCP server+ βββ Compress (~9MB β ~3MB)++Stage 4: MODELS (profile-dependent)+ βββ offline: Download GGUF models, build ruvLLM+ βββ hybrid: Download small model + encrypt keys+ βββ cloud: Encrypt API keys only++Stage 5: DATA+ βββ Initialize AgentDB with RVF backend+ βββ Build HNSW indexes for default patterns+ βββ Snapshot pre-trained SONA weights+ βββ Cache plugin registry++Stage 6: VERIFY+ βββ Bundle test script (sh, no dependencies)+ βββ Generate expected-results manifest+ βββ Include checksum of all sections++Final: Assemble RVFA+ βββ Write magic + version + header+ βββ Append all sections with offsets+ βββ Compute and append footer SHA256+ βββ Output: ruflo.rvf+```++### 4.3 Size Targets++| Profile | Sections | Compressed Size |+|---------|----------|-----------------|+| `cloud` | Kernel + Runtime + Ruflo + Data + Verify | ~60MB |+| `hybrid` | All + Phi-3-mini-Q4 | ~2GB |+| `offline` | All + Phi-3 + Qwen2.5-Coder-3B | ~4GB |++---++## 5. Architecture++### 5.1 Component Diagram++```+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+β ruflo.rvf (RVFA) β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β KERNEL: Alpine Linux 3.23 (~5MB) β β+β β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β+β β β RUNTIME: Node.js 22 + Claude Code CLI β β β+β β β βββββββββββββββββββββββββββββββββββββββββββββββββ β β+β β β β RUFLO v3.5+ ββ β β+β β β β βββ 26 CLI commands (140+ subcommands) ββ β β+β β β β βββ 60+ agent definitions ββ β β+β β β β βββ 17 hooks + 12 workers ββ β β+β β β β βββ MCP server (215 tools) ββ β β+β β β β βββ AgentDB + HNSW (RVF backend) ββ β β+β β β β βββ Security + Claims + Plugins ββ β β+β β β βββββββββββββββββββββββββββββββββββββββββββββββββ β β+β β β βββββββββββββββββββββββββββββββββββββββββββββββββ β β+β β β β MODELS ββ β β+β β β β βββ ruvLLM inference engine ββ β β+β β β β βββ Local: Phi-3 / Qwen2.5-Coder (GGUF) ββ β β+β β β β βββ Cloud: encrypted API key vault ββ β β+β β β βββββββββββββββββββββββββββββββββββββββββββββββββ β β+β β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β DATA: AgentDB + SONA patterns + Plugin registry β β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β VERIFY: 95-check capability suite + checksums β β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+ β β β+ ββββββ΄βββββ ββββββ΄βββββ ββββββ΄βββββ+ βContainerβ βMicroVM β β Native β+ β (OCI) β β(Firecrk)β β (dev) β+ βββββββββββ βββββββββββ βββββββββββ+```++### 5.2 Model Routing Flow++```+User Task+ β+ βΌ+βββββββββββββββββββ+β Complexity Check β+β (hooks route) β+ββββββββββ¬βββββββββ+ β+ ββββββ΄βββββββββββββββββββββββββ+ β β+ βΌ βΌ+ Simple (<30%) Complex (>30%)+ β β+ βΌ βΌ+ββββββββββββ βββββββββββββββ+β Tier 1: β β ruvLLM local?β+β Agent β ββββββββ¬βββββββ+β Booster β Yes β No+β (WASM) β ββββββ΄βββββ+β <1ms, $0 β β β+ββββββββββββ βΌ βΌ+ ββββββββββββ ββββββββββββ+ β Tier 2: β β Tier 3: β+ β Phi-3 β β Cloud APIβ+ β (local) β β (Sonnet/ β+ β ~200ms β β Opus) β+ β $0 β β 2-5s β+ ββββββββββββ ββββββββββββ+```++---++## 6. Security++### 6.1 Appliance Integrity++| Mechanism | Purpose |+|-----------|---------|+| RVFA footer SHA256 | Tamper detection for entire appliance |+| Per-section SHA256 | Integrity of individual sections |+| Code signing (Ed25519) | Verify publisher identity |+| API key vault (AES-256-GCM) | Protect cloud credentials |+| Read-only rootfs | Prevent runtime modification of system files |+| Namespace isolation | Container/VM boundary enforcement |+| Seccomp profile | Restrict syscalls to minimum required |++### 6.2 Key Management++```+Boot:+ 1. User provides passphrase OR hardware key+ 2. Derive AES key via Argon2id (memory-hard)+ 3. Decrypt .env.enc β load API keys into memory+ 4. Keys exist only in process memory (never on disk)+ 5. On shutdown: zero memory, drop keys+```++### 6.3 Update Security++```+Hot Update Flow:+ 1. Download signed patch (.rvfp)+ 2. Verify Ed25519 signature against pinned public key+ 3. Verify patch targets correct appliance version+ 4. Apply patch to target section+ 5. Recompute section SHA256 + footer hash+ 6. Run VERIFY suite to confirm no regression+ 7. Atomic swap (old β .bak, new β active)+```++---++## 7. Implementation Plan++### Phase 1: RVFA Format + Builder (Week 1-2)++| Task | Description |+|------|-------------|+| Define RVFA binary spec | Magic bytes, header schema, section table |+| `ruflo-appliance build` | Multi-stage builder with profile selection |+| `ruflo-appliance inspect` | Header + section manifest viewer |+| `ruflo-appliance extract` | Unpack all sections to directory |+| Cloud profile | Kernel + Runtime + Ruflo + encrypted keys |++### Phase 2: Runtime + Verification (Week 3-4)++| Task | Description |+|------|-------------|+| `ruflo-appliance run` | Boot sequence with container isolation |+| `ruflo-appliance verify` | 95-check capability suite |+| `ruflo-appliance mcp` | MCP server mode (stdio + SSE) |+| DATA section | Pre-built AgentDB + HNSW + SONA |+| CI integration | Build appliance on every release |++### Phase 3: ruvLLM Integration (Week 5-8)++| Task | Description |+|------|-------------|+| ruvLLM engine | GGUF model loader + KV-cache + streaming |+| Model routing | 3-tier routing (Booster β local β cloud) |+| Hybrid profile | Small local model + cloud fallback |+| Offline profile | Full local inference, no network |+| Offline verification | All 95 checks pass without network |++### Phase 4: Distribution + Updates (Week 9-10)++| Task | Description |+|------|-------------|+| `ruflo-appliance update` | Hot-patch individual sections |+| Ed25519 signing | Code signing for appliance + patches |+| IPFS distribution | Publish appliances to decentralized storage |+| MicroVM support | Firecracker/Cloud Hypervisor isolation |+| Documentation | User guide, API reference, examples |++---++## 8. Consequences++### Positive++- **Zero-install deployment**: One file, no Node.js/npm/Claude Code prerequisites+- **Offline-capable**: Full agent orchestration without internet (offline profile)+- **Reproducible**: Same binary = same behavior everywhere+- **Secure**: Encrypted keys, signed updates, container isolation+- **Fast boot**: <5s from cold start (vs 35s for `npx ruflo@latest`)+- **Verifiable**: Built-in 95-check suite proves every capability works+- **Updatable**: Hot-patch sections without rebuilding entire appliance++### Negative++- **Larger artifact**: 60MB-4GB depending on profile (vs ~9MB npm package)+- **Build complexity**: Multi-stage builder with cross-compilation+- **Model storage**: Local models consume significant disk (2-4GB per model)+- **Update latency**: Section-level patches still require verification pass++### Mitigations++- Cloud profile keeps size at ~60MB (comparable to a Docker image)+- Builder is automated and reproducible via CI+- Model quantization (Q4_K_M) reduces size while maintaining quality+- Verification suite runs in parallel (~10s for full 95-check pass)++---++## 9. Alternatives Considered++| Alternative | Reason Rejected |+|-------------|----------------|+| Docker image only | Requires Docker installed; no offline model support; not a single file |+| Flatpak/Snap | Linux-only packaging; no custom binary format; no model bundling |+| AppImage | Linux-only; no Windows/macOS; limited isolation |+| WebAssembly bundle | No filesystem access; can't run Claude Code CLI; no local models |+| Nix derivation | Requires Nix; steep learning curve; no model bundling |+| VM image (qcow2) | Too large; requires hypervisor; not portable |++RVFA provides the best balance of portability, size, isolation, and integration with the existing RVF ecosystem.++---++## 10. References++- ADR-057: RVF Native Storage Backend+- ADR-054: RVF-Powered Plugin Marketplace+- ADR-056: agentic-flow v3 Integration+- [llama.cpp GGUF format](https://github.com/ggerganov/llama.cpp)+- [Firecracker MicroVM](https://firecracker-microvm.github.io/)+- [OCI Image Spec](https://github.com/opencontainers/image-spec)