# AGENTS.md

`kvenginepb` sits inside the Cloud Storage Engine workspace (`../..`). Root files `Cargo.toml` and `build.rs` define the crate and wire up code generation; `src/*.proto` are the canonical schemas, while their generated `*.rs` siblings plus `lib.rs` expose the Rust API.

## Guidelines

- Never modify generated `.rs` files directly -- change the `.proto`, then rebuild using `cargo build -p kvenginepb` in the Cloud Storage Engine workspace.

- Generated Rust code are very long. Prefer reading from protobuf definition files instead, unless you want to debug generated code.

An example generated Rust code looks like this (generated by `protobuf` crate):

```rust
pub struct FtsPackedFileInfo {
  // message fields
  pub id: u64,
  pub meta_offset: u32,
  // special fields
  pub unknown_fields: ::protobuf::UnknownFields,
  pub cached_size: ::protobuf::CachedSize,
}

impl FtsPackedFileInfo {
  pub fn new() -> FtsPackedFileInfo {
    Default::default()
  }
  pub fn get_id(&self) -> u64 {
    ...
  }
  pub fn set_id(&mut self, v: u64) {
    ...
  }
  ...
}
```

- To construct Protobuf objects, use code pattern as below -- It is compact, explicit, while keeping compiling errors when new fields are introduced later:

```rust
let info = FtsPackedFileInfo {
  id: 123,
  meta_offset: 456,

  unknown_fields: Default::default(),
  cached_size: Default::default(),
};
```

- Prefer access message fields directly, to compact the code, e.g. `info.id`, `info.smallest`, etc. However, for nested messages, prefer to use `get_xxx()`, `mut_xxx()` to avoid handling with `Option`. For example:

```protobuf
message OffsetSize {
  uint64 offset = 1;
  uint64 size = 2;
}

message TantivyIndexLayout {
  OffsetSize meta = 1;
  OffsetSize managed = 2;
}
```

If you want to set `meta.offset`, use:

```rust
layout.mut_meta().offset = 123;
// meta field is a sub-message, so we use get_meta() / mut_meta() accessor
// offset field is a primitive type, so we prefer direct access to be compact
```

## Core Structures

**ChangeSet Operations:**

- `Flush` - MemTable to L0 SSTable operations
- `Compaction` - LSM-Tree level merging operations
- `Snapshot` - Complete shard state capture
- `Split` - Shard split operations
- `FtsUpdate` - Unified FTS metadata updates (tracked indexes, L0/L1 files, snap watermark)
- `ColumnarCompaction` - Columnar storage operations
- `UpdateVectorIndex` - Vector index updates

## Core Files

- `src/changeset.proto` - Defines `ChangeSet` and related messages for tracking storage engine state changes
- `src/fts.proto` - Defines Full-Text Search structures including `FullTextIndexDef`, packed file formats, and dedicated file structures
- `src/lib.rs` - Library interface with utility functions
- `build.rs` - Protobuf code generation build script
- Generated files (`changeset.rs`, `fts.rs`) are created in `src/` during build