worktable 0.9.0-alpha8

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

WorkTable is an in-memory storage library with optional on-disk persistence. It uses a proc-macro (`worktable!`) to generate type-safe table structures with primary keys, secondary indexes, and custom queries.

## Build and Test Commands

```bash
# Build the project
cargo build

# Run all tests
cargo test

# Run a specific test
cargo test test_name

# Run tests with verbose output
cargo test --verbose

# Lint (must pass with no warnings)
cargo clippy --all-targets --all-features -- -D warnings
```

## Architecture

### Core Components

- **`WorkTable<Row, PrimaryKey, ...>`** - Main container holding data pages, primary index, secondary indexes, lock manager, and primary key generator
- **`DataPages`** - Manages fixed-size memory pages storing serialized rows using `rkyv`
- **`PrimaryIndex`** - B-tree index mapping primary keys to row locations (Links)
- **`SecondaryIndexes`** - Generated struct holding secondary indexes for non-PK lookups
- **`LockMap`** - Row-level locking with RAII `LockGuard` for concurrent access

### Key Modules

| Module | Purpose |
|--------|---------|
| `src/in_memory/` | Data page storage (`DataPages`, `Data`) |
| `src/index/` | Primary and secondary index implementations |
| `src/lock/` | Async row-level locking with `Lock` and `LockGuard` |
| `src/persistence/` | On-disk persistence engine and CDC operations |
| `src/table/` | Core `WorkTable` struct and query builders |
| `codegen/` | Proc-macro crate generating table boilerplate |

### Macro Usage

Tables are defined using the `worktable!` macro which generates:
- `<Name>WorkTable` - The table struct
- `<Name>Row` - Row type with all columns
- `<Name>PrimaryKey` - Newtype wrapper for the primary key
- Query structs and methods based on the `queries` section

```rust
worktable!(
    name: Test,
    columns: {
        id: u64 primary_key autoincrement,
        field: i64,
        optional_field: u64 optional,
    },
    indexes: {
        field_idx: field unique,
    },
    queries: {
        update: { FieldById(field) by id },
        delete: { ByField() by field },
        in_place: { FieldById(field) by id }
    }
);
```

### Row Locking Pattern

The locking system uses RAII guards. `LockGuard` automatically releases locks and cleans up the lock map entry on drop:

```rust
let guard = LockGuard::new(lock, lock_map, pk);
// Lock is held
// Lock automatically released when guard goes out of scope
```

### CDC (Change Data Capture)

Methods suffixed with `_cdc` (e.g., `insert_cdc`, `reinsert_cdc`) return `Operation` structs containing change events for both primary and secondary indexes. These are used by the persistence layer.

### Persistence

The `persistence` module provides:
- `PersistenceEngine` - Applies operations to disk
- `PersistenceTask` - Background task for async persistence
- `Operation` enum - Insert/Update/Delete operations with CDC events

## Workspace Structure

The project is a Cargo workspace with members:
- Main `worktable` crate
- `codegen` - proc-macro crate
- `examples` - usage examples
- `performance_measurement` - optional perf measurement feature