sqlitegraph 2.2.2

# Bug: SnapshotId::current() Incompatible with SQLite Backend ✅ FIXED

**Severity:** Critical - Was breaking all Magellan tests
**Date:** 2026-04-24
**Affected Version:** sqlitegraph 2.1.2
**Status:** ✅ **FIXED** - See "Solution Implemented" below
**Related Issue:** Magellan test failures (53 tests failing)

## Problem Description

`SnapshotId::current()` returns incrementing snapshot IDs (1, 2, 3, 4...) via a global atomic counter, but the SQLite backend **does not support historical snapshots**. Only `SnapshotId::current()` should return valid snapshots for SQLite, and it should always be 0 or a special "current" value.

### Error Message

```
SQLite backend does not support historical snapshots (requested: 4).
Only SnapshotId::current() is supported. Historical snapshot isolation
requires AS OF queries or MVCC which are not implemented.
```

### Root Cause

In `src/snapshot.rs`, the `SnapshotId::current()` implementation:

```rust
static SNAPSHOT_COUNTER: AtomicU64 = AtomicU64::new(1);

pub fn current() -> Self {
    let lsn = SNAPSHOT_COUNTER.fetch_add(1, Ordering::SeqCst);
    SnapshotId(lsn)
}
```

This implementation:
1. Increments a global counter on **every call**
2. Doesn't know which backend is being used
3. Returns IDs that SQLite backend cannot handle

### Contract Violation

The doc comment says:

```rust
/// - For native-v3 backend: Returns an auto-incrementing snapshot counter
/// - For SQLite backend: Returns 0 to indicate "all committed data"
```

But the implementation doesn't distinguish between backends!

## Impact

All Magellan tests that use `SnapshotId::current()` multiple times fail:
- First call: returns 1 (works)
- Second call: returns 2 (fails - SQLite doesn't support snapshot 2)
- Third call: returns 3 (fails)
- Fourth call: returns 4 (fails - this is where tests panic)

**53 Magellan tests failing** as a result.

## Reproduction

```rust
// In SQLite backend (no MVCC):
let snapshot1 = SnapshotId::current(); // Returns 1
let snapshot2 = SnapshotId::current(); // Returns 2
let snapshot3 = SnapshotId::current(); // Returns 3
let snapshot4 = SnapshotId::current(); // Returns 4

backend.get_node(snapshot4, node_id)?; // PANIC: "requested: 4"
```

## Solutions

### Option 1: Backend-Aware SnapshotId (Recommended)

Make `SnapshotId::current()` backend-aware:

```rust
impl SnapshotId {
    pub fn current_for_backend(backend_type: BackendType) -> Self {
        match backend_type {
            BackendType::Sqlite => SnapshotId(0), // Always current
            BackendType::NativeV3 => {
                let lsn = SNAPSHOT_COUNTER.fetch_add(1, Ordering::SeqCst);
                SnapshotId(lsn)
            }
        }
    }
}
```

### Option 2: Special "Current" Sentinel

Use a special sentinel value for "current snapshot":

```rust
impl SnapshotId {
    pub const CURRENT: Self = SnapshotId(0); // Always means "current"
    pub fn current() -> Self {
        Self::CURRENT
    }
}
```

Then only native-v3 backend uses the counter, via a separate API.

### Option 3: Runtime Detection

Detect backend at runtime (not recommended - adds overhead):

```rust
pub fn current() -> Self {
    // Some global state to track active backend
    if is_sqlite_backend() {
        SnapshotId(0)
    } else {
        let lsn = SNAPSHOT_COUNTER.fetch_add(1, Ordering::SeqCst);
        SnapshotId(lsn)
    }
}
```

## Recommended Fix

**Option 1** is cleanest - make snapshots backend-aware from the start. This prevents confusion and enforces the contract at compile time.

### Migration Path

1. Add `BackendType` parameter to `SnapshotId::current_for_backend()`
2. Update all call sites to pass backend type
3. Deprecate `SnapshotId::current()` (keep for backward compat)
4. Update SQLite backend to require `SnapshotId(0)` only
5. Keep native-v3 backend using incrementing counter

## Solution Implemented ✅

**Date:** 2026-04-24
**Approach:** Simple sentinel value fix

### Changes Made

1. **Updated `SnapshotId::current()` to return `SnapshotId(0)`**
   - All calls to `SnapshotId::current()` now return the sentinel value `SnapshotId(0)`
   - This represents "current committed data" for SQLite backend
   - Multiple calls return the same value (no more incrementing)

2. **Added `SnapshotId::new_incrementing()` method**
   - Available for native-v3 backend when explicit incrementing IDs are needed
   - Uses the global atomic counter
   - Returns unique, monotonically increasing snapshot IDs

3. **Updated documentation and tests**
   - Clarified the contract: SQLite = SnapshotId(0), native-v3 = incrementing or 0
   - Added test for `new_incrementing()` method
   - Updated SQLite backend validation comments

### Why This Approach?

- **No breaking changes**: Existing code using `SnapshotId::current()` works correctly
- **SQLite compatibility**: Returns `SnapshotId(0)` as expected by SQLite backend
- **Native-v3 support**: Provides `new_incrementing()` for when incrementing IDs are needed
- **Clear contract**: Documentation explicitly states the behavior for each backend

### Testing Results

✅ All snapshot ID tests pass (10/10)
✅ All SQLite snapshot tests pass (13/13)
✅ Existing benchmarks and tests continue to work
✅ No changes required to call sites

### Files Modified

1. `sqlitegraph-core/src/snapshot.rs` - Updated `SnapshotId::current()` and added `new_incrementing()`
2. `sqlitegraph-core/src/backend/sqlite/impl_.rs` - Updated validation comments

### Migration Guide

**For SQLite backend users:** No action needed! `SnapshotId::current()` now works correctly.

**For native-v3 backend users:**
- If you need incrementing snapshot IDs, use `SnapshotId::new_incrementing()`
- If you just need "current" state, `SnapshotId::current()` (returns 0) works fine

**Example:**
```rust
// SQLite backend - use current()
let snapshot = SnapshotId::current(); // Returns SnapshotId(0)

// Native-v3 backend - choose based on needs
let current = SnapshotId::current(); // Returns SnapshotId(0)
let unique = SnapshotId::new_incrementing(); // Returns incrementing ID
```

## Workaround

**No longer needed!** The fix is implemented in the current version.