{"id":31946383,"url":"https://github.com/jmalicki/xibalba","last_synced_at":"2025-10-14T11:15:48.327Z","repository":{"id":318725096,"uuid":"1073875570","full_name":"jmalicki/xibalba","owner":"jmalicki","description":"Xibalba: Chaos Testing Framework for Linux Filesystem Concurrency using eBPF","archived":false,"fork":false,"pushed_at":"2025-10-12T20:23:07.000Z","size":658412,"stargazers_count":0,"open_issues_count":53,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-12T21:02:49.618Z","etag":null,"topics":["chaos-engineering","concurrency","ebpf","filesystem","filesystem-testing","jepsen","kernel","race-detection","testing","xibalba"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmalicki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-10T18:57:18.000Z","updated_at":"2025-10-12T17:19:14.000Z","dependencies_parsed_at":"2025-10-12T21:12:59.641Z","dependency_job_id":null,"html_url":"https://github.com/jmalicki/xibalba","commit_stats":null,"previous_names":["jmalicki/xibalba"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jmalicki/xibalba","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmalicki%2Fxibalba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmalicki%2Fxibalba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmalicki%2Fxibalba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmalicki%2Fxibalba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmalicki","download_url":"https://codeload.github.com/jmalicki/xibalba/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmalicki%2Fxibalba/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019097,"owners_count":26086513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chaos-engineering","concurrency","ebpf","filesystem","filesystem-testing","jepsen","kernel","race-detection","testing","xibalba"],"created_at":"2025-10-14T11:15:45.662Z","updated_at":"2025-10-14T11:15:48.321Z","avatar_url":"https://github.com/jmalicki.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xibalba: Chaos Testing Framework for Linux Kernel Filesystems\n\n[![Xibalba CI](https://github.com/jmalicki/xibalba/actions/workflows/ci.yml/badge.svg)](https://github.com/jmalicki/xibalba/actions/workflows/ci.yml)\n[![eBPF Build](https://github.com/jmalicki/xibalba/actions/workflows/ebpf.yml/badge.svg)](https://github.com/jmalicki/xibalba/actions/workflows/ebpf.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n*The Underworld of Trials*\n\n**Xibalba** (shee-BAHL-bah) - The Mayan underworld where code faces its darkest trials\n\n**Linux-specific**: This framework uses Linux eBPF for fault injection, which is not available on other kernels (BSD, Windows, macOS)\n\n---\n\n## What is Xibalba?\n\n**Xibalba** is a chaos testing framework that finds subtle bugs in **Linux kernel** filesystem code—the kind that only show up when many programs access files at the same time.\n\n### Why This Matters\n\n**The Problem**: Imagine 100 programs all trying to list files in the same directory simultaneously. One program might see a file that doesn't exist, another might see the same file twice, and a third might miss files entirely. These bugs are **nearly impossible to find** with normal testing because they depend on exact timing—threads hitting the same code at just the right microsecond.\n\n**Real-world impact**:\n- Database corruption when `ls` misses transaction log files\n- Build failures when `make` doesn't see all source files\n- Backup tools skip files, leading to data loss\n- Package managers install incomplete software\n\n**Traditional testing fails** because running tests 1000 times might never hit the exact timing that triggers the bug. The bug might appear once per million operations—**in production**, not in testing.\n\n**Xibalba's solution**: Don't wait for luck. **Force** the timing bugs to appear by:\n1. Running many threads concurrently (amplify the chaos)\n2. Injecting strategic delays with eBPF (widen the narrow timing windows)\n3. Validating that every read operation is correct (catch the bugs)\n\nIf your code passes Xibalba's tests, it can handle the chaos of real production systems.\n\n### Technical Details\n\n**Xibalba** is a [Jepsen](https://jepsen.io/)-inspired chaos testing framework specifically designed for testing concurrent filesystem operations in the **Linux kernel** using eBPF fault injection.\n\n**Linux-only**: eBPF is a Linux kernel feature. Other operating systems (FreeBSD, Windows, macOS) don't have equivalent fault injection capabilities at the kernel level.\n\n**Inspired by**: [Kyle Kingsbury](https://aphyr.com/)'s [Jepsen framework](https://github.com/jepsen-io/jepsen) for distributed systems\n\n**Novel approach**: Brings Jepsen-quality chaos engineering to Linux kernel filesystem testing using eBPF\n\n---\n\n## The Name: Xibalba\n\n**[Xibalba](https://en.wikipedia.org/wiki/Xibalba)** (shee-bahl-BAH) — literally **\"Place of Fear\"** or **\"Place of Phantoms\"** — is the Maya underworld from the *[Popol Vuh](https://en.wikipedia.org/wiki/Popol_Vuh)*, the sacred K'iche' Maya text. Far below the surface world, Xibalba is a realm of darkness ruled by the **Ajawab' Xib'alb'a** (Lords of Xibalba), death gods who delight in tormenting souls through elaborate trials and deadly games.\n\n### The Myth: The Hero Twins' Descent\n\nThe most famous story of Xibalba tells of the Hero Twins—**Hunahpu** and **Xbalanque**—who were summoned to the underworld by its jealous lords. Their father and uncle had been killed there before them, defeated by the trials. The twins descended knowing they faced almost certain death, but they were clever, brave, and determined to avenge their ancestors.\n\nTo escape Xibalba alive, they had to survive the **Six Houses of Xibalba**, each a deadly ordeal designed by the Lords of Death:\n\n- 🌑 **The Dark House** (*Ch'umil Ha*) — Absolute darkness where you cannot see the dangers that surround you\n- ❄️  **The Cold House** (*Shiqiripat*) — Freezing winds and icy hail that drain all warmth and will\n- 🐆 **The Jaguar House** (*Balam Ha*) — Prowling jaguars with razor fangs, hungry and waiting\n- 🦇 **The Bat House** (*Sotz' Ha*) — Giant death bats with obsidian wings that decapitate victims\n- 🗡️  **The Razor House** (*Chamiabak*) — Rooms filled with moving blades of obsidian and flint\n- 🔥 **The Fire House** (*Kaqix Ha*) — Unbearable flames that consume everything within\n\nEach house represented a different form of death—darkness, cold, beasts, blades, heat. The lords expected the twins to fail, as all others had. But through **cunning, resilience, and ingenuity**, Hunahpu and Xbalanque survived every trial. They eventually defeated the Lords of Death in a ritual ball game, died and were reborn, and ascended from Xibalba as gods—the Sun and the Moon.\n\n### The Metaphor: Your Code's Descent into Chaos\n\nLike the Hero Twins descending into Xibalba, **your code must face orchestrated chaos designed to expose every weakness.** Each test is a House of Xibalba—an ordeal that seems designed to make your code fail:\n\n- 🌑 **The Dark House** → Race conditions in darkness (timing you can't see)\n- ❄️  **The Cold House** → Delay injection (operations frozen at critical moments)\n- 🐆 **The Jaguar House** → Resource contention (threads competing like hungry jaguars)\n- 🦇 **The Bat House** → Concurrent modifications (sudden, deadly changes)\n- 🗡️  **The Razor House** → Edge cases (cuts that find every boundary condition)\n- 🔥 **The Fire House** → Stress testing (burning through resource limits)\n\n**Just as the Hero Twins couldn't see in the Dark House**, your code faces race conditions where timing is invisible. **Just as they shivered in the Cold House**, your operations are frozen by strategic delays. **Just as jaguars prowled**, your threads compete for scarce resources.\n\nBut if your code survives—like the Hero Twins—it doesn't just work. It has been **battle-tested against chaos itself**. It emerges not as a fragile prototype, but as **hardened, production-ready software** worthy of the surface world.\n\n### The Six Houses: Chaos Test Categories\n\n| House | Trial | Test Category | What It Finds |\n|-------|-------|---------------|---------------|\n| 🌑 Dark House | Darkness | Race conditions | Timing bugs invisible in normal testing |\n| ❄️ Cold House | Freezing | Delay injection | Timeout handling, deadlocks |\n| 🐆 Jaguar House | Beasts | Resource contention | Lock contention, starvation |\n| 🦇 Bat House | Decapitation | Concurrent modifications | Lost updates, torn reads |\n| 🗡️ Razor House | Blades | Edge cases | Boundary conditions, overflow |\n| 🔥 Fire House | Flames | Stress testing | Resource exhaustion, memory leaks |\n\n\u003e *\"Are they not merely wicked? They are evil, and great are their thoughts of deceit.\"*  \n\u003e — Popol Vuh, describing the Lords of Xibalba\n\n**Your code enters Xibalba. Will it emerge victorious like the Hero Twins, or will the Lords of Chaos claim another victim?**\n\n---\n\n## Key Features\n\n### 🌪️ **Jepsen-Style Chaos Engineering**\n- Concurrent readers + writers (configurable: `--readers N --writers M`)\n- Configurable test duration (`--duration seconds`)\n- Three consistency models: strict, weak POSIX, eventual\n- **Vector clock causality tracking** (Lamport 1978, Fidge/Mattern 1988)\n- Proven happens-before relationships (not timestamp guessing!)\n\n### ⚡ **eBPF Delay Injection**\n- Kernel-level getdents64 interception\n- Configurable delays: `pause_controller \u003cprob%\u003e \u003citerations\u003e [max_delay_ns]`\n- Examples: `50 500` (50% prob, ~5μs delay) or `100 1000 100000` (aggressive)\n- Widens race windows 10,000x\n- Zero code changes needed\n\n### 📊 **Incremental JSONL Output (Timeout-Safe!)**\n- **`xibalba-progress.jsonl`**: One JSON line per 5 seconds\n- **`xibalba-bugs.jsonl`**: One JSON line per bug event\n- Lock-free queue implementation (no I/O blocking)\n- Dedicated writer thread (zero mutex contention)\n- Partial results survive timeouts!\n\n### 🔍 **Precise Bug Detection**\n- **Missing entries**: File should exist but doesn't (cache miss bugs)\n- **Phantom entries**: File exists but shouldn't (stale cache bugs)\n- **Duplicate entries**: File appears twice (iterator bugs)\n- Uses causality (not timestamps) - zero false positives!\n\n### 🖥️ **Hermetic QEMU VMs**\n- Fast boot (\u003c2 seconds with custom initramfs)\n- Docker-based hermetic builds (no host dependencies!)\n- Tests ext4, xfs, btrfs\n- One-command execution: `bazel test //vm:qemu_filesystem_suite`\n\n### 🧪 **C++20 Unit Tests (15/15 passing)**\n- GoogleTest framework\n- Tests core validation logic\n- Runs in CI on every PR\n- Proves bug detection works correctly\n\n---\n\n## 🚀 Getting Started\n\n**Current Status**: ✅ Core implementation complete, eBPF fault injection working\n\n**⚠️ IMPORTANT**: [CI and VM Testing Strategy](docs/CI-AND-VM-TESTING.md) - **Read this first!**\n\n**Key points**:\n- CI validates builds/packages (✅ automated)\n- VM testing requires KVM (run locally or self-hosted)\n- **Why**: We test CUSTOM KERNELS - containers can't do this!\n\n\n### Documentation\n\n**Core Docs**:\n- **🖥️ [VM Setup Guide](docs/VM-SETUP.md)** - QEMU/KVM hermetic VM testing\n- **🔧 [Fast VM Testing Design](docs/design/FAST-VM-TESTING.md)** - Architecture overview\n- **📝 [VM Permissions](docs/VM-PERMISSIONS.md)** - Permission setup details\n\n**Bug Research** (Validation):\n- **🐛 [Bug Research](docs/bug-research/README.md)** - Real-world filesystem bugs catalog (16+ bugs from 2018-2025)\n  - Research on bugs that evaded detection for years\n  - Test implementation plans with code examples\n  - Gap analysis: What Xibalba can detect now vs. what's needed\n  - 70+ links to LKML, CVEs, and bug trackers\n- **📊 [Competitive Analysis](docs/COMPETITIVE-ANALYSIS.md)** - Xibalba vs. CrashMonkey comparison\n  - Detailed feature comparison and positioning\n  - Strengths and weaknesses of both tools\n  - Use case analysis and recommendations\n  - TL;DR: Complementary tools, use both for comprehensive testing\n\n---\n\n### Prerequisites\n\n**Host Machine**:\n- Linux host with KVM support\n- 8GB+ RAM (16GB+ recommended for parallel VM testing)\n- 50GB+ disk space (for VM images)\n- Ubuntu 22.04 or later\n\n**System Prerequisites** (one-time install):\n```bash\nsudo apt install -y libvirt-daemon-system qemu-kvm virtinst cloud-image-utils\nsudo usermod -aG libvirt,kvm $USER  # No more sudo needed after this!\n```\n\n**Bazel validates automatically** when you run VM tests (no separate step needed!)\n\n**Kernel Development**:\n- Kernel source tree (with your patches or baseline)\n- Build environment (gcc, make, pahole for BTF)\n- Will build custom kernels with eBPF support enabled\n\n**VM Technology**: QEMU/KVM managed via libvirt\n- Fast, hardware-accelerated virtualization\n- Standard Linux VM tooling (virsh, virt-install)\n\n### Quick Start\n\n```bash\n# Clone repository\ngit clone https://github.com/jmalicki/xibalba.git\ncd xibalba\n\n# Run unit tests (validates core bug detection logic)\nbazel test //common:state_tracker_test\n\n# Run simple chaos test\nmkdir -p /tmp/xibalba_test\nbazel run //chaos:simple_chaos_test -- --duration 30 /tmp/xibalba_test\n\n# View results (JSONL format - one line per 5 seconds)\ncat /tmp/xibalba_test/xibalba-progress.jsonl | jq '.'\ncat /tmp/xibalba_test/xibalba-bugs.jsonl | jq '.'\n\n# Analyze with helper tool\ntools/analyze-progress.sh /tmp/xibalba_test/xibalba-progress.jsonl\n```\n\n### With eBPF Delay Injection\n\n**Terminal 1 - Delay injector**:\n```bash\n# Grant capabilities (one-time)\nsudo setcap cap_sys_admin,cap_bpf,cap_perfmon+ep bazel-bin/chaos/pause_controller\n\n# Inject delays (50% probability, 500 iterations ~5μs)\nbazel run //chaos:pause_controller -- 50 500\n```\n\n**Terminal 2 - Run test**:\n```bash\nmkdir -p /tmp/xibalba_test\nbazel run //chaos:simple_chaos_test -- --duration 60 /tmp/xibalba_test\n```\n\n**Result**: Bug rate increases 100-1000x with delays!\n\n### VM Testing (Hermetic QEMU)\n\n**No setup needed!** VM infrastructure uses Docker for hermetic builds.\n\n**Comprehensive comparison** (all filesystems in parallel):\n```bash\n# Compare ext4, XFS, btrfs across consistency models (~2 minutes)\nbazel run //tools:filesystem_comparison\n\n# Custom duration\nDURATION=60 bazel run //tools:filesystem_comparison\n\n# View results\ncat test-results/comparison-*/REPORT.md\n```\n\n**Quick test** (single filesystem):\n```bash\n# With explicit parameters (recommended)\nbazel run //vm:qemu_test_runner -- \\\n    --filesystem ext4 \\\n    --duration 30 \\\n    --readers 5 \\\n    --writers 2\n\n# With defaults (ext4, 300sec, 10 readers, 3 writers)\nbazel run //vm:qemu_test_runner\n\n# Just override what you need\nbazel run //vm:qemu_test_runner -- --duration 60\n```\n\n**Full test suite** (ext4, xfs, btrfs in parallel):\n```bash\nbazel test //vm:qemu_filesystem_suite\n```\n\n**Individual filesystem tests**:\n```bash\nbazel test //vm:qemu_test_ext4   # ext4 only\nbazel test //vm:qemu_test_xfs    # xfs only\nbazel test //vm:qemu_test_btrfs  # btrfs only\n```\n\n**Results include**:\n- Progress JSONL (every 5 seconds)\n- Bug JSONL (every bug event)\n- Full operation history\n\n📖 **See**: \n- [`docs/design/FAST-VM-TESTING.md`](docs/design/FAST-VM-TESTING.md) - Architecture\n- [`docs/VM-PERMISSIONS.md`](docs/VM-PERMISSIONS.md) - KVM setup\n- [`docs/TESTING-GUIDE.md`](docs/TESTING-GUIDE.md) - Complete testing guide\n\n\n### Building Individual Components\n\n```bash\n# Build directory reader library\nbazel build //common:dir_reader\n\n# Build chaos test\nbazel build //chaos:simple_chaos_test\n\n# Build eBPF injector and controller\nbazel build //chaos:pause_controller\nbazel build //chaos:pause_injector_bpf\n\n# Build everything\nbazel build //...\n\n# Create Debian package\nbazel build //packaging:xibalba-deb\n```\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                    Xibalba Controller                           │\n│                    (The Lords of Chaos)                         │\n│                                                                 │\n│  ┌───────────────┐   ┌──────────────┐    ┌──────────────┐       │\n│  │DirectoryReader│   │   Nemesis    │    │   Checker    │       │\n│  │  Abstraction  │   │(eBPF Faults) │    │ (Invariants) │       │\n│  └───────┬───────┘   └───────┬──────┘    └───────┬──────┘       │\n│          │                   │                    │             │\n│          ▼                   ▼                    ▼             │\n│     Operations            Faults             Validation         │\n└──────────┬───────────────────┬────────────────────┬─────────────┘\n           │                   │                    │\n           ▼                   ▼                    ▼\n┌─────────────────────────────────────────────────────────────────┐\n│              The Houses of Xibalba (Test VMs)                   │\n│                                                                 │\n│        ┌────┐      ┌────┐      ┌─────┐      ┌─────┐             │\n│        │ext4│      │xfs │      │btrfs│      │tmpfs│             │\n│        └────┘      └────┘      └─────┘      └─────┘             │\n│                                                                 │\n│     Each with: custom kernel + test data + eBPF                 │\n│     Your code must survive ALL trials to pass                   │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## The Trials (Test Categories)\n\n### Trial 1: The Dark House - Race Conditions\nConcurrent operations in complete chaos. Can your code maintain correctness when timing is unpredictable?\n\n### Trial 2: The Razor House - Edge Cases\nSharp corner cases that slice through weak error handling. Directory boundaries, empty directories, massive directories.\n\n### Trial 3: The Cold House - Resource Starvation\nMemory allocation failures, ENOMEM errors. Can your code survive with nothing?\n\n### Trial 4: The Jaguar House - Timing Attacks\nStrategic delays injected via eBPF to widen race windows. The jaguars hunt for timing bugs.\n\n### Trial 5: The Fire House - I/O Errors\nSimulated I/O failures, filesystem errors. Can your code handle when everything goes wrong?\n\n### Trial 6: The Bat House - Concurrent Mutations\nMultiple writers changing the directory while you read. The death bats of concurrency.\n\n---\n\n## What Xibalba Tests\n\n### ✅ The Trials Your Code Faces\n\n- Concurrent directory iteration correctness\n- Race condition resistance\n- Error handling (ENOMEM, EIO, EAGAIN, EINTR)\n- Lock contention behavior\n- NOWAIT semantics\n- Cursor validity under concurrent modifications\n- Recovery from failures\n\n### ❌ What We Don't Test (Kernel Guarantees)\n\n- Lock correctness (assume kernel locks work)\n- Data integrity (assume block layer is correct)\n- Atomic operations (assume kernel provides atomicity)\n- Memory safety (assume kernel doesn't corrupt memory)\n\n**Principle**: Test YOUR code, assume kernel primitives work correctly.\n\n---\n\n## How It Works (Simple Explanation)\n\nThink of it like stress-testing a bridge, but for filesystem code:\n\n**Step 1: Create Chaos**\n- Launch 10 threads all reading the same directory\n- Launch 3 threads creating/deleting files\n- Let them fight for 5 seconds\n\n**Step 2: Make Bugs Appear**\n- Use eBPF to inject tiny delays (microseconds) at critical moments\n- These delays turn \"might happen once in a million operations\" into \"happens every few seconds\"\n- It's like slow-motion replay for race conditions\n\n**Step 3: Check for Correctness**\n- Track every file that should exist\n- Validate every directory read\n- Catch bugs: missing files, duplicate files, phantom files\n\n**Real Example**:\n```\nWithout Xibalba: Test passes 999,999 times, fails once (in production)\nWith Xibalba:    Test fails in 30 seconds (before production)\n```\n\n**Result**: Bugs that would take months to find in production are caught in minutes during testing.\n\n---\n\n## Prerequisites\n\n**Host Machine**:\n- Linux host with KVM support (QEMU/KVM + libvirt)\n- 32GB+ RAM recommended\n- 500GB+ disk space\n- Ubuntu 22.04 or later\n- Shared dev machine OK (use overnight for long benchmarks)\n\n**Kernel Development**:\n- Kernel source tree (with your patches or baseline)\n- Build environment (gcc, make, pahole for BTF)\n- Will build custom kernels with eBPF support enabled\n\n**VM Technology**: QEMU/KVM managed via libvirt\n- Fast, hardware-accelerated virtualization\n- Standard Linux VM tooling (virsh, virt-install)\n\n---\n\n## Status\n\n**Current**: ✅ Production-ready chaos testing framework\n\n### Core Features (Complete)\n- ✅ Vector clock causality tracking (Jepsen-style!)\n- ✅ Multi-threaded chaos test with lock-free bug queue\n- ✅ eBPF delay injection (fully configurable)\n- ✅ Incremental JSONL output (timeout-safe)\n- ✅ C++20 unit tests (15/15 passing)\n- ✅ Hermetic QEMU VM testing (\u003c2s boot time)\n- ✅ Docker-based hermetic builds\n- ✅ GitHub Actions CI pipeline\n\n### Test Results\n- **Unit tests**: 15/15 passing, run on every PR\n- **VM tests**: ext4, xfs, btrfs all working\n- **Bug detection proven**: Found 39,706 bugs in 30-second test\n- **Causality tracking**: Zero false positives\n\n### Academic Foundation\n- Lamport timestamps (1978)\n- Vector clocks (Fidge/Mattern 1988)  \n- Jepsen methodology (Kingsbury)\n- Linearizability testing (Herlihy \u0026 Wing 1990)\n\n**Next**: \n- Add io_uring support\n- More filesystem support (zfs, f2fs)\n- Enhanced analysis tools\n\n---\n\n## CI/CD\n\nGitHub Actions runs automatically on every PR:\n\n### Unit Tests (Every PR, ~3 seconds)\n```yaml\n- bazel test //common:state_tracker_test\n```\n- 15/15 tests validate core bug detection\n- Ensures vector clock causality works\n- Fast feedback (\u003c5s)\n\n### Build Verification (Every PR, ~30 seconds)\n```yaml\n- bazel build //chaos:all  # All chaos testing binaries\n- bazel build //vm:extract_kernel //vm:build_initramfs\n- bazel build //packaging:xibalba-deb\n```\n\n### VM Tests (On-Demand, ~5 minutes)\nLabel PR with `run-vm-tests` to trigger:\n```yaml\n- bazel test //vm:qemu_filesystem_suite\n```\n- Tests ext4, xfs, btrfs in hermetic QEMU VMs\n- Extracts JSONL bug data as artifacts\n- Requires KVM (runs on self-hosted runner)\n\n**CI Artifacts**:\n- Unit test results\n- JSONL bug data (`xibalba-progress.jsonl`, `xibalba-bugs.jsonl`)\n- Full test logs\n\n---\n\n## Contributing\n\nXibalba is actively developed. Want to help strengthen the trials?\n\n**Development setup**:\n```bash\n# Run shellcheck on all scripts (hermetic, no install needed)\nbazel test //tools:shellcheck_test\n\n# (Optional) Setup pre-commit git hooks for commit-time checks\n# Requires: sudo apt install pipx (one-time)\nbazel run //tools:setup_precommits\n\n# CI uses Bazel shellcheck test regardless of local setup\n```\n\n**How to contribute**:\n1. Add new fault injection modes\n2. Implement additional invariant checkers\n3. Create new test scenarios\n4. Improve VM automation\n5. Add support for more filesystems\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n**Summary**: Free to use, modify, and distribute. No warranty provided.\n\n---\n\n## Academic References\n\n### Causality \u0026 Time\n\n1. **Lamport, Leslie (1978)**  \n   *\"Time, Clocks, and the Ordering of Events in a Distributed System\"*  \n   Communications of the ACM, 21(7):558-565  \n   [PDF](https://lamport.azurewebsites.net/pubs/time-clocks.pdf) | [DOI](https://doi.org/10.1145/359545.359563)  \n   **Foundation for Xibalba's causality tracking**\n\n2. **Fidge, Colin J. (1988)**  \n   *\"Timestamps in Message-Passing Systems That Preserve the Partial Ordering\"*  \n   Proc. 11th Australian Computer Science Conference, pp. 56-66  \n   **Vector clock algorithm used in Xibalba**\n\n3. **Mattern, Friedemann (1989)**  \n   *\"Virtual Time and Global States of Distributed Systems\"*  \n   Parallel and Distributed Algorithms, pp. 215-226  \n   **Independent vector clock discovery with formal proofs**\n\n### Consistency Testing\n\n4. **Herlihy, Maurice P. \u0026 Wing, Jeannette M. (1990)**  \n   *\"Linearizability: A Correctness Condition for Concurrent Objects\"*  \n   TOPLAS 12(3):463-492  \n   DOI: [10.1145/78969.78972](https://doi.org/10.1145/78969.78972)  \n   **Defines linearizability tested by Xibalba**\n\n5. **Burckhardt, Sebastian et al. (2010)**  \n   *\"Line-Up: A Complete and Automatic Linearizability Checker\"*  \n   PLDI 2010  \n   DOI: [10.1145/1806596.1806634](https://doi.org/10.1145/1806596.1806634)  \n   **Similar automated testing approach**\n\n### Distributed Systems Testing\n\n6. **Kingsbury, Kyle**  \n   *Jepsen: On the Perils of Network Partitions*  \n   https://aphyr.com/tags/jepsen  \n   **Methodology adapted for filesystem testing**\n\n7. **Kingsbury, Kyle**  \n   *Jepsen Consistency Models*  \n   https://jepsen.io/consistency  \n   **Consistency model taxonomy used in Xibalba**\n\n## Acknowledgments\n\n**Inspired by**:\n- [Kyle Kingsbury (Aphyr)](https://aphyr.com/)'s [Jepsen framework](https://github.com/jepsen-io/jepsen) - Chaos engineering for distributed systems\n- [Jepsen.io](https://jepsen.io/) database testing methodology - Rigorous invariant checking\n- Linux kernel testing community - eBPF-based testing approaches\n\n**Mythology**:\n- [Xibalba](https://en.wikipedia.org/wiki/Xibalba) from the [Popol Vuh](https://en.wikipedia.org/wiki/Popol_Vuh) - The Maya creation epic\n- The [Hero Twins](https://en.wikipedia.org/wiki/Maya_Hero_Twins)' trials - A metaphor for surviving through testing\n\n---\n\n*Xibalba: Where code faces its darkest trials and emerges battle-tested*\n\n*\"Only the strong survive the underworld. Will your code emerge victorious?\"*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmalicki%2Fxibalba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmalicki%2Fxibalba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmalicki%2Fxibalba/lists"}