> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locking and Verification

> File locking and integrity verification APIs

memvid-core provides APIs for file locking and integrity verification that host applications can use directly.

***

## File Locking

Memvid uses OS-level file locks to manage concurrent access:

```rust theme={null}
use memvid_core::{Memvid, OpenReadOptions};

// Writers get exclusive lock
let mut mv = Memvid::open("notes.mv2")?;

// Readers share the lock
let mv_read = Memvid::open_read_only("notes.mv2")?;

// Optional: allow repair if the file needs recovery (may take an exclusive lock)
let mv_repair = Memvid::open_read_only_with_options(
    "notes.mv2",
    OpenReadOptions { allow_repair: true },
)?;
```

### Lock Behavior

* **Writers** take an exclusive `FileLock`
* **Readers** share a read lock (multiple concurrent readers allowed)
* Locks are released when the `Memvid` handle is dropped

### Checking Lock Status

CLI commands for inspecting locks:

```bash theme={null}
# Check who holds the lock
memvid who notes.mv2

# Request the writer to release
memvid nudge notes.mv2
```

***

## Verification

Verify file integrity with the core API:

```rust theme={null}
use memvid_core::{Memvid, VerificationStatus};

// Basic verification
let report = Memvid::verify("notes.mv2", false)?;

// Deep verification (more thorough)
let report = Memvid::verify("notes.mv2", true)?;

// Check results
if report.overall_status == VerificationStatus::Passed {
    println!("File is valid");
} else {
    for check in &report.checks {
        println!("{}: {:?}", check.name, check.status);
    }
}
```

### Verification Checks

The verification report includes:

| Check                   | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `TimeIndexRead`         | Time index readable (or skipped if disabled)    |
| `TimeIndexEntryCount`   | Track entry count matches manifest              |
| `TimeIndexSortOrder`    | Deep mode: timestamps sorted                    |
| `LexIndexDecode`        | Lexical index readable (or skipped if disabled) |
| `VecIndexDecode`        | Vector index readable (or skipped if disabled)  |
| `WalPendingRecords`     | No uncommitted WAL records                      |
| `FrameCountConsistency` | Stats match TOC frame count                     |

***

## Doctor (Repair)

Repair corrupted or damaged files:

```rust theme={null}
use memvid_core::{Memvid, DoctorOptions};

// Rebuild time index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_time_index: true,
    ..Default::default()
})?;

// Rebuild lexical index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_lex_index: true,
    ..Default::default()
})?;

// Rebuild vector index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_vec_index: true,
    ..Default::default()
})?;

// Vacuum deleted frames
Memvid::doctor("notes.mv2", DoctorOptions {
    vacuum: true,
    ..Default::default()
})?;

// Full repair
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_time_index: true,
    rebuild_lex_index: true,
    rebuild_vec_index: true,
    vacuum: true,
    ..Default::default()
})?;
```

### Doctor Report

The doctor command returns a report with:

* **Findings**: Issues detected (INFO, WARN, ERROR severity)
* **Planned Actions**: Repairs that will be performed
* **Status**: Result of each repair action

***

## Single-File Verification

Memvid enforces the “single-file guarantee” at open/create time. If it detects sidecars (e.g. `notes.mv2-wal`), it fails with `MemvidError::AuxiliaryFileDetected`.

```rust theme={null}
use memvid_core::{Memvid, MemvidError};

match Memvid::open("notes.mv2") {
    Ok(_mv) => println!("opened successfully"),
    Err(MemvidError::AuxiliaryFileDetected { path }) => {
        eprintln!("auxiliary file detected: {}", path.display());
    }
    Err(err) => eprintln!("open failed: {err}"),
}
```

For an explicit directory scan, use the CLI command `memvid verify-single-file <file>`.

***

## CLI Commands

The CLI exposes these APIs:

```bash theme={null}
# Verify integrity
memvid verify notes.mv2 --deep

# Repair issues
memvid doctor notes.mv2 --rebuild-time-index --rebuild-lex-index

# Check single-file compliance
memvid verify-single-file notes.mv2

# Inspect locks
memvid who notes.mv2
memvid nudge notes.mv2
```

***

## Error Handling

The core API exposes structured errors via `MemvidError`:

```rust theme={null}
use memvid_core::{Memvid, MemvidError};

match Memvid::open("notes.mv2") {
    Ok(mv) => { /* success */ }
    Err(MemvidError::Locked(locked)) => {
        let pid = locked.owner.as_ref().and_then(|owner| owner.pid);
        println!("File locked (pid={pid:?}): {}", locked.message);
    }
    Err(e) => { /* other error */ }
}
```

***

## Best Practices

### Concurrent Access

1. **Use read-only mode** for queries to allow concurrent readers
2. **Keep write sessions short** to minimize lock contention
3. **Handle LockedError** gracefully with retry logic

### Integrity Maintenance

1. **Verify periodically** (weekly or after large ingestions)
2. **Run doctor** after crashes or power failures
3. **Vacuum** after bulk deletions to reclaim space

### Recovery Workflow

```bash theme={null}
# 1. Verify the file
memvid verify notes.mv2 --deep

# 2. If issues found, preview repairs
memvid doctor notes.mv2 --plan-only

# 3. Apply repairs
memvid doctor notes.mv2 --rebuild-time-index --rebuild-lex-index

# 4. Verify again
memvid verify notes.mv2 --deep
```