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

cargo build                          # Build all crates
cargo test                           # Run all tests (unit + integration + compile-fail)
cargo test --test integration        # Run only integration tests
cargo test --test integration TESTNAME  # Run a single integration test
cargo test --test compile_fail       # Run compile-fail tests (trybuild)
cargo bench --bench region           # Run benchmarks (criterion)
MIRIFLAGS="-Zmiri-permissive-provenance" cargo +nightly miri test -p nearest --lib --test integration  # Run tests under Miri
cargo xtask fmt                      # Format code
cargo xtask fmt --check              # Check formatting
cargo xtask lint                     # Clippy + format check (-D warnings)
cargo xtask lint --fix               # Auto-fix clippy + formatting
cargo doc --no-deps --all --all-features  # Build documentation (-D warnings in CI)
cargo deny check                     # License/advisory/ban auditing

Requires nightly Rust (nightly-2026-02-10 pinned in rust-toolchain) for #![feature(offset_of_enum)].

nearest is a self-relative pointer library for region-based allocation. The entire data graph lives in a single contiguous byte buffer; all internal pointers are stored as i32 offsets relative to their own address, making Clone a plain memcpy with no pointer fixup.

• nearest/ — Main library: Near<T>, NearList<T>, Region<T>, Session, traits (Flat, Emit, Patch)
• nearest-derive/ — Proc-macro crate: #[derive(Flat)] and #[derive(Emit)]
• xtask/ — Dev automation (fmt, lint)

1. Construction: Region::new(T::make(...)) → derive-generated Emit writes values and patches self-relative offsets
2. Reading: Region<T>: Deref<Target=T>, Near<T>: Deref<Target=T> (computes self_addr + offset)
3. Mutation: region.session(|s| { ... }) opens a branded session; mutations are append-only (old data becomes dead bytes)
4. Compaction: region.trim() deep-copies only reachable data into a fresh buffer

• flat.rs — Generates Flat impls: enum repr validation, deep_copy body for structs/enums
• emit.rs — Generates Emit impls: make() factories, __Builder structs, NearList codegen
• emit_proxy.rs — Emit for proxy enums dispatching to inner builders
• util.rs — FieldKind classification (Primitive/Near/NearList/OptionNear/Other)

• Provenance: Uses expose_provenance/with_exposed_provenance for self-relative pointer resolution
• Branding: Ghost-cell pattern with for<'id> lifetime prevents Ref escape from session and cross-session use (enforced at compile time)
• No-Drop: Derive macro emits const { assert!(!needs_drop::<T>()) } to reject types with Drop
• Alignment: Buffer aligned to max(align_of::<Root>(), 8)
• pub(crate) never relaxes safety invariants: If a function has unsafe preconditions, it must be unsafe fn regardless of visibility. pub(crate) restricts who can call it, not whether callers must uphold safety invariants.

Releases are automated with release-plz. On every push to main, the GitHub Action opens (or updates) a release PR that bumps versions and updates CHANGELOG.md. Merging that PR publishes to crates.io and creates a GitHub release with a v<version> tag.

• Config: release-plz.toml
• Workflow: .github/workflows/release-plz.yml
• Only nearest and nearest-derive are published; xtask is excluded
• nearest owns the changelog and git tags (v{{ version }}); nearest-derive is bumped in lockstep without its own changelog or tags

Use Conventional Commits — release-plz uses them to determine version bumps and generate changelog entries.

<type>[optional scope]: <description>

[optional body]

• 2-space indentation, max 100 columns
• Imports: reordered, grouped by StdExternalCrate, granularity Crate
• Clippy: pedantic + nursery at warn; dbg_macro, allow_attributes, missing_safety_doc, undocumented_unsafe_blocks denied
• Dual-licensed: Apache-2.0 OR MIT