If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/spacejam/sled shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 5w ago
• 3 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live spacejam/sled repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/spacejam/sled.

What it runs against: a local clone of spacejam/sled — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in spacejam/sled | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 63 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of spacejam/sled. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/spacejam/sled.git
#   cd sled
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of spacejam/sled and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "spacejam/sled(\\.git)?\\b" \\
  && ok "origin remote is spacejam/sled" \\
  || miss "origin remote is not spacejam/sled (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/tree.rs" \\
  && ok "src/tree.rs" \\
  || miss "missing critical file: src/tree.rs"
test -f "src/db.rs" \\
  && ok "src/db.rs" \\
  || miss "missing critical file: src/db.rs"
test -f "src/leaf.rs" \\
  && ok "src/leaf.rs" \\
  || miss "missing critical file: src/leaf.rs"
test -f "src/config.rs" \\
  && ok "src/config.rs" \\
  || miss "missing critical file: src/config.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 63 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~33d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/spacejam/sled"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Sled is a pure-Rust transactional embedded database designed as a BTreeMap-like key-value store optimized for flash and SSDs. It provides ACID transactions, lock-free concurrency, zero-copy reads, and crash-safe durability—all compiled into a single Rust binary without external dependencies like SQLite or RocksDB. Monolithic Cargo workspace (single Cargo.toml at root) containing the core database implementation in src/ with modules like src/db.rs (main Db struct), src/tree.rs (tree operations), src/leaf.rs (B-tree leaves), src/block_checker.rs (crash recovery), and src/sync/ (lock-free primitives). Examples in examples/ (bench.rs, structured.rs) and fuzzing harness in fuzz/fuzz_targets/fuzz_model.rs demonstrate usage.

Rust application developers building embedded storage systems who need a lightweight, crash-safe database (like in desktops apps, edge services, or data-intensive tools) without the overhead of running a separate database server or linking C libraries.

Pre-production (v1.0.0-alpha.124 as of latest): the repo shows professional structure with CI via .github/workflows/test.yml and comprehensive safety/security docs (SAFETY.md, SECURITY.md), but the README warns of an 'in-progress rewrite' on main. The project has active maintenance (RELEASE_CHECKLIST.md exists) and fuzzing infrastructure (fuzz/ directory), but the alpha tag indicates API volatility.

Moderate risk: single maintainer (Tyler Neely), alpha stability stage, and the README explicitly states it is 'out of sync with the main branch which contains a large in-progress rewrite'—meaning breaking changes are likely. Dependency count is reasonable (~15 direct), but reliance on experimental crates like ebr (epoch-based reclamation) and custom concurrent-map adds complexity. Use only for non-production systems until 1.0.0 stable.

The repository is undergoing a major rewrite on the main branch (per README warning), with focus on crash-safety verification (event_verifier.rs, block_checker.rs) and log-structured optimizations. Testing infrastructure is active (.github/workflows/test.yml), but specific PRs and issues are not visible in provided metadata.

git clone https://github.com/spacejam/sled.git
cd sled
cargo build
cargo test

Daily commands: This is a library, not a server. To run examples: cargo run --example bench or cargo run --example structured. For tests: cargo test. Fuzzing: cd fuzz && cargo +nightly fuzz run fuzz_model.

• src/lib.rs — Entry point and public API surface; defines the main Db and Tree types that all users interact with
• src/tree.rs — Core B-tree implementation; contains the primary data structure logic for insertions, deletions, and range queries
• src/db.rs — Database engine and transaction coordinator; manages object lifecycle, crash recovery, and persistence
• src/leaf.rs — Leaf node abstraction; handles serialization and in-memory representation of key-value pairs
• src/config.rs — Configuration builder and runtime settings; defines all tunable parameters affecting performance and behavior
• ARCHITECTURE.md — Design documentation essential for understanding system invariants, crash recovery guarantees, and module responsibilities
• src/metadata_store.rs — Persistent metadata tracking and crash recovery; critical for durability guarantees and restart correctness

Add a New Configuration Option

1. Add the new field to the Config struct in src/config.rs (src/config.rs)
2. Add a builder method like fn with_my_option(mut self, value: Type) -> Self in the impl block (src/config.rs)
3. Update Db::new() in src/db.rs to read and use the config value (src/db.rs)
4. Write a test in tests/test_tree.rs verifying the option affects behavior (tests/test_tree.rs)

Add a New Operation to the Tree API

1. Define the method signature on the Tree struct in src/tree.rs (src/tree.rs)
2. Implement the logic using atomic operations and maintaining B-tree invariants (src/tree.rs)
3. Re-export the method in src/lib.rs if it should be public (src/lib.rs)
4. Add functional tests in tests/test_tree.rs and crash-recovery tests in tests/crash_tests/ (tests/test_tree.rs)

Improve Crash Recovery or Durability

1. Document the invariant and recovery scenario in ARCHITECTURE.md (ARCHITECTURE.md)
2. Add recovery logic to src/event_verifier.rs or src/metadata_store.rs (src/event_verifier.rs)
3. Create a crash-injection test in tests/crash_tests/ that simulates the failure (tests/crash_tests/mod.rs)
4. Verify recovery with tests/test_crash_recovery.rs (tests/test_crash_recovery.rs)

Debug Memory Leaks or Allocation Issues

1. Enable the testing-shred-allocator feature in Cargo.toml for leak detection (Cargo.toml)
2. Run tests with custom allocator instrumentation in src/alloc.rs (src/alloc.rs)
3. Use tests/test_space_leaks.rs to measure memory overhead and detect regressions (tests/test_space_leaks.rs)

• Pure Rust (no C FFI) — Memory safety guarantees without C bindings; prevents use-after-free and buffer overflows in persistence layer
• B-tree for ordered data — Enables efficient range queries and maintains log(n) complexity for lookups; balances cache locality with update cost
• Epoch-based flushing — Decouples writes from durability; allows batching and reduces fsync frequency while maintaining crash consistency
• Lock-free concurrent primitives (queue, stack) — Scales to many cores without contention; critical for high-throughput concurrent workloads
• Event log + metadata store for recovery — Enables fast recovery by replaying events rather than full tree traversal; supports point-in-time safety

• Beta status with no stability guarantees on-disk format

  • Why: Allows architectural improvements without maintaining backward compatibility; trades user friction for future flexibility
  • Consequence: Cannot use in production systems requiring long-term data migration paths; suitable for applications tolerating occasional data rebuilds

• In-memory object cache with LRU eviction

  • Why: Avoids repeated deserialization of hot nodes; improves throughput at the cost of memory overhead
  • Consequence: Workloads larger than available RAM may thrash; users must tune cache size or accept degraded performance

• Epoch-based flushing instead of per-operation durability

  • Why: Batches I/O to reduce fsync calls; dramatically improves write throughput
  • Consequence: Small risk window between in-memory modification and durable flush; crash during that window can lose recent writes

• Single-threaded background recovery and flush tasks

  • Why: Simplifies coordination logic and avoids complex locking around recovery state
  • Consequence: Recovery speed limited to single-core throughput; very large databases may require extended startup time

• Network distribution or replication (single-machine embedded database only)
• Dynamic schema or RDBMS features (key-value store, not relational)
• Real-time consistency guarantees beyond epoch-based durability
• Compatibility with existing embedded database formats (fresh implementation)
• Complex query language (supports only get/insert/delete/range operations)
• Encryption at rest (application responsibility)

No required env vars or external services, but be aware: (1) The monotonic-behavior feature disables object ID reuse and tree merges—use only for deterministic testing, not production. (2) Build profile overrides in Cargo.toml set panic = "abort" in test/release, so .unwrap() will hard-crash rather than panic—test thoroughly. (3) The README is explicitly out of sync; refer to ARCHITECTURE.md and source code as ground truth. (4) Fuzzing requires cargo +nightly, not stable Rust. (5) Memory-mapped I/O via fs2 requires proper file permissions and can conflict on some filesystems (e.g., tmpfs without proper backing).

• Log-Structured Merge Trees (LSM) — Sled's core design uses LSM principles for flash-optimized sequential writes; understanding LSM trade-offs (read amplification vs. write efficiency) is essential to tuning the database.
• Epoch-Based Reclamation (EBR) — Used via the ebr crate for lock-free memory safety; critical to understanding how sled avoids traditional locks in concurrent operations.
• MVCC (Multi-Version Concurrency Control) — Sled implements snapshot isolation via MVCC-like mechanisms to provide serializable transactions without blocking; essential for understanding isolation levels.
• B-Tree Structure — Sled's range queries, sorted iteration, and balancing rely on B-tree invariants; modifications to src/leaf.rs require B-tree knowledge.
• Write-Ahead Logging (WAL) — Sled's crash-recovery strategy depends on WAL in src/block_checker.rs; understanding WAL semantics is critical for correctness in failure scenarios.
• Compare-and-Swap (CAS) / Atomic Operations — Sled exposes CAS (Tree::compare_and_swap) for lock-free client-side coordination; the entire sync module relies on CAS primitives.
• Memory Mapping & Page Tables — Sled uses the pagetable crate and memory-mapped I/O (fs2) for zero-copy reads; understanding mmap trade-offs and platform limits is important for large datasets.

• spacejam/meli — Sister project by same author; demonstrates embedded storage patterns and ecosystem integration with sled.
• tikv/rocksdb — Industry-standard embedded key-value store in C++; sled is a pure-Rust alternative targeting similar use cases with fewer dependencies.
• meilisearch/meilisearch — High-level search engine built on embedded database principles; shows typical consumer of sled-like storage libraries.
• paritytech/substrate — Blockchain framework using embedded databases for state storage; represents a major production user of sled concepts.
• sqlite/sqlite — Canonical embedded SQL database; sled is a lower-level alternative for key-value workloads without SQL overhead.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive crash recovery tests for metadata_store.rs

The repo has crash_tests/crash_metadata_store.rs but it's minimal. Given that sled is a transactional embedded database, metadata store corruption during crashes is critical. The metadata_store.rs module handles persistent state, and more targeted crash scenarios (partial writes, power loss during compaction, concurrent metadata updates) would significantly improve reliability confidence.

• [ ] Examine existing tests/crash_tests/crash_metadata_store.rs to understand current coverage
• [ ] Review src/metadata_store.rs to identify failure points (journal writes, compaction, field updates)
• [ ] Add crash scenarios: mid-write interrupts, concurrent metadata access during recovery, malformed metadata headers
• [ ] Add assertions verifying metadata consistency post-recovery in tests/crash_tests/crash_metadata_store.rs
• [ ] Run with ASAN/MSAN via scripts/sanitizers.sh to catch memory issues

Add integration tests for object_location_mapper.rs with concurrent access patterns

The object_location_mapper.rs module maps objects to storage locations but has no dedicated test file. This is critical for correctness in concurrent scenarios. tests/test_tree.rs likely covers it indirectly, but explicit tests for mapping consistency under high concurrency (with rayon), location reuse, and garbage collection would catch subtle bugs early.

• [ ] Create tests/test_object_location_mapping.rs
• [ ] Add tests for concurrent inserts/updates with location mapping verification
• [ ] Add tests verifying location reuse after deletion (fragmentation behavior)
• [ ] Test with monotonic-behavior feature disabled to verify location recycling correctness
• [ ] Use rayon to spawn parallel access patterns and verify no location conflicts

Add pre-commit hook and CI workflow for SAFETY.md audit compliance

The repo has SAFETY.md documenting unsafe blocks, but there's no automated enforcement. The .github/workflows/test.yml doesn't include unsafe code audits. Adding a CI check that scans src/ for new unsafe blocks and requires them to be documented in SAFETY.md would prevent regressions and maintain the safety-first culture.

• [ ] Create .github/workflows/safety-audit.yml that runs on PR
• [ ] Add a script scripts/check_unsafe_blocks.sh that parses src/**/*.rs for 'unsafe' keywords
• [ ] Cross-reference found unsafe blocks against SAFETY.md to ensure they're documented
• [ ] Fail CI if undocumented unsafe code is detected
• [ ] Add pre-commit hook template in CONTRIBUTING.md referencing the safety script

• Add comprehensive doctests to src/lib.rs covering all public APIs (Tree::insert, Tree::range, Db::transaction). Currently only README examples exist.
• Expand the structured.rs example with more complex schema patterns (nested types, migrations) and add corresponding unit tests in examples/ to demonstrate that structured data path.
• Add documentation and tests for merge operators under src/ (implied by README feature mention but no visible implementation guide); create examples/merge_ops.rs showing real-world use cases.

• High · Unsafe Code in Lock-Free Data Structures — src/sync/*, src/tree.rs, src/heap.rs, src/object_cache.rs, and other core modules. The codebase extensively uses unsafe Rust code in core lock-free algorithms and data structures (as acknowledged in SECURITY.md). The developers explicitly state 'memory issues relating to the lock-free data structures in their colder failure paths' as an area with 'elevated risk'. Lock-free structures are notoriously difficult to implement correctly and can lead to use-after-free, data races, or memory corruption in edge cases. Fix: 1) Increase fuzz testing coverage specifically targeting concurrent access patterns and failure scenarios. 2) Consider external security audits of lock-free implementations. 3) Add extensive comments documenting memory ordering guarantees and safety invariants. 4) Use tools like ThreadSanitizer and Miri regularly in CI/CD. 5) Consider replacing particularly risky unsafe code with proven concurrent libraries where feasible.
• High · Deprecated Rust Edition (2024) — Cargo.toml (edition field). The Cargo.toml specifies edition = '2024', which does not exist. Rust editions are: 2015, 2018, 2021. This is either a typo or a configuration error that could cause build failures and prevent proper compilation with standard toolchains. This may prevent security updates from being applied properly. Fix: Correct the edition to '2021' (or '2018' for older MSRV compatibility). This should be: edition = "2021"
• Medium · Incomplete Dependency in Cargo.toml — Cargo.toml (dev-dependencies section, last line). The dev-dependencies section ends with 'ra' as an incomplete entry without version specification. This suggests copy-paste error or incomplete refactoring. While this appears in dev-dependencies only, it indicates potential build configuration issues and lack of validation. Fix: 1) Complete or remove the incomplete 'ra' dependency entry. 2) Validate Cargo.toml with 'cargo check'. 3) Add pre-commit hooks to validate Cargo.toml syntax.
• Medium · Panic Abort in Release Builds — Cargo.toml ([profile.release] section). The release profile specifies panic = 'abort', which causes the entire process to terminate on any panic. While this can improve performance, it prevents graceful error handling and recovery. In a database context, an unexpected panic could lead to data corruption or loss if not properly handled at application level. Fix: 1) Use panic = 'unwind' to allow for proper error recovery. 2) Ensure all unsafe code paths are thoroughly tested and cannot panic. 3) Document the implications of abort behavior in SAFETY.md. 4) Consider using Result-based error handling instead of panics in fallible operations.
• Medium · Experimental/Alpha Version in Production — Cargo.toml (version field). The package version is '1.0.0-alpha.124', indicating this is pre-release software. While this is documented, deploying alpha software in production environments without understanding stability implications poses security risks, as the API and behavior may change significantly. Fix: 1) Clearly document in README that this is alpha software unsuitable for production without extensive testing. 2) Add STABILITY.md with detailed notes on breaking changes and known issues. 3) Establish a clear path to stable 1.0.0 release. 4) Maintain detailed changelog of all versions.
• Medium · Testing Features May Hide Issues in Production — Cargo.toml ([features] section). Multiple testing-only features exist (testing-shred-allocator, testing-count-allocator, for-internal-testing-only, monotonic-behavior) that alter runtime behavior. If these are accidentally enabled in production builds, they could cause performance degradation or unexpected behavior. Fix: 1) Use cfg guards to prevent testing features in release builds. 2) Add documentation about which features should never be enabled in production. 3) Consider separating test dependencies into a separate crate. 4) Add CI checks to verify testing features are not enabled in release builds.
• Low · Overflow Checks Enabled in Release — Cargo. While overflow-checks = true in release builds is generally good for security, it has performance implications. The setting should be explicitly justified for a performance-critical embedded database. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.