randomio 0.2.0

# Randomio Project Guide

## Project Overview

**Randomio** is a Rust library that defines minimal capability traits for asynchronous, offset-addressable I/O. It is currently in the **design specification phase** with documentation-complete but implementation-pending status.

The project defines:
> "Can this device read/write bytes at arbitrary offsets asynchronously?"

### Design Philosophy

- **Zero policy**: No buffering, batching, or scheduling opinions
- **Zero-cost abstraction**: No allocation, dynamic dispatch, or `async_trait` macros
- **Device agnostic**: Works for files, block devices, object stores, network storage, io_uring, WASM
- **Capability, not policy**: Traits describe what backends CAN do, not how callers SHOULD use them

## Technology Stack

- **Language**: Rust (Edition 2024)
- **Version**: 0.1.0 (working toward 1.0.0 API freeze)

## Project Structure

```
randomio/
├── Cargo.toml          # Package manifest
├── Cargo.lock          # Dependency lock file
├── .gitignore          # Ignores /target directory
├── AGENTS.md           # This file
├── src/                # Source directory (currently empty — implementation pending)
├── docs/
│   ├── primitive.md    # Current core specification (v1.0) — PRIMARY REFERENCE
│   └── API.md.bak      # Older comprehensive API spec (superseded by primitive.md)
└── target/             # Build artifacts
```

## Build Commands

Since `src/` is currently empty, the project builds as an empty library:

```bash
# Build the project
cargo build

# Build for release
cargo build --release

# fmt
cargo fmt

# lint
cargo clippy

# Clean build artifacts
cargo clean
```

## Code Style Guidelines

### From the Specification (docs/primitive.md)

1. **Poll-based APIs only**: `async fn` is forbidden in core traits. Use `poll_*` methods:

   ```rust
   fn poll_write_at(
       self: Pin<&mut Self>,
       cx: &mut Context<'_>,
       offset: u64,
       buf: &[u8],
   ) -> Poll<io::Result<()>>;
   ```

2. **Trait requirements**:
   - Traits require `Send`
   - Traits do NOT require `Sync`
   - Backends may assume exclusive mutable read (`&mut self`)

3. **Zero-allocation**: APIs must:
   - Allocate nothing
   - Avoid dynamic dispatch
   - Be inlineable
   - Match OS primitives closely

4. **Naming conventions**:
   - `AsyncRandomWrite` — Core write capability
   - `AsyncRandomRead` — Optional read capability
   - `poll_*` prefix for poll-based methods

## Core Types and Traits

### Types (Frozen for 1.x)

```rust
/// Half-open byte interval [start, end)
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct Range {
    pub start: u64,
    pub end: u64,
}

/// Data block at specific offset
pub struct Block<B = bytes::Bytes> {
    pub offset: u64,
    pub data: B,
}
```

### Traits (Frozen for 1.x)

**AsyncRandomWrite** — Core write capability:

```rust
pub trait AsyncRandomWrite {
    fn poll_write_at(/* ... */) -> Poll<io::Result<()>>;
    fn poll_flush(/* ... */) -> Poll<io::Result<()>>;
    fn poll_sync(/* ... */) -> Poll<io::Result<()>>;
}
```

**AsyncRandomRead** — Optional read capability:

```rust
pub trait AsyncRandomRead {
    fn poll_read_at(/* ... */) -> Poll<io::Result<()>>;
}
```

## Testing Strategy

Currently no tests exist (empty `src/`). Planned testing approach per specification:

- **Memory backend** for unit testing (see docs/primitive.md §7)
- Fuzz testing framework integration (see docs/API.md.bak §10.3)
- Backends to test: `tokio::fs::File`, memory, mock object stores

## Stability Policy

### Frozen Forever (1.x)

- Trait method signatures
- Trait semantics
- `Block` struct
- `Range` struct

### Additive Only

- New traits
- New structs
- Extension traits
- Feature flags
- Additional implementations

## What This Crate Does NOT Provide

Per the specification, the following are explicitly out of scope:

- ❌ Buffering
- ❌ Batching
- ❌ Ordering guarantees
- ❌ Durability tracking beyond OS
- ❌ Scheduling
- ❌ Sink/Stream adapters
- ❌ Runtime abstractions
- ❌ Device detection
- ❌ Filesystem helpers
- ❌ `async fn` wrappers in core traits

## Recommended Architecture (Future)

```
randomio-core        ← traits only (this crate, frozen)
randomio-sink        ← buffering/commit/durable ranges
randomio-uring       ← io_uring backend
randomio-tokio       ← tokio adapters
randomio-mem         ← testing backend
randomio-wal         ← write-ahead log runtime
```

## Key Documentation Files

| File | Purpose |
|------|---------|
| `docs/primitive.md` | **Current** core specification — start here for implementation |
| `docs/API.md.bak` | Older comprehensive spec with additional context (superseded) |

## Security Considerations

1. **Buffer ownership**: Submitting a `Block` transfers `Bytes` ownership to the sink
2. **No drop commit**: Dropping a sink does NOT call `commit()` — explicit call required
3. **Cancellation**: In-flight writes may be partially completed on task cancellation
4. **Thread safety**: `Send` but not `Sync` — callers must provide external synchronization

## Development Status

- **Current**: Specification complete, implementation pending
- **Goal**: 1.0.0 API freeze with minimal frozen surface
- **Next steps**: Implement core types (`Range`, `Block`) and traits (`AsyncRandomWrite`, `AsyncRandomRead`)