@spec clear_stale_readers(LeanLmdb.Environment.t()) ::
  {:ok, non_neg_integer()} | {:error, reason()}

Checks the LMDB reader table and clears slots left by terminated processes.

Returns {:ok, cleared_count}. Active readers are never cleared. This is backed by heed's Env::clear_stale_readers and may be called while the environment is in use. Invalid handles and native failures return {:error, reason}.

@spec compare_exchange(
  LeanLmdb.Database.t(),
  binary(),
  compare_expected(),
  compare_replacement()
) :: :ok | {:conflict, :missing | binary()} | {:error, reason()}

Atomically compares a key's current state and applies a replacement on match.

:missing is distinct from an expected empty binary. A mismatch returns the exact current state as {:conflict, :missing} or {:conflict, binary} and never mutates the database. Missing deletes after a successful comparison are idempotent. A match returns :ok; malformed arguments and native failures return {:error, reason}. Conflict binaries are copied before return.

@spec create_database(LeanLmdb.Environment.t(), binary()) ::
  {:ok, LeanLmdb.Database.t()} | {:error, reason()}

Creates a named binary database, or reopens it when it already exists.

Names must contain 1..511 bytes of valid UTF-8 and may not contain NUL. Returns {:ok, database} or {:error, reason}; read-only environments cannot create databases. The immutable database handle retains its environment.

@spec delete(LeanLmdb.Database.t(), binary()) :: :ok | {:error, reason()}

Deletes key if present.

Deletion is idempotent: both present and missing keys return :ok. Validation, read-only, and LMDB failures return {:error, reason}.

@spec get(LeanLmdb.Database.t(), binary()) ::
  {:ok, binary()} | :not_found | {:error, reason()}

Gets the binary value for key.

Returns {:ok, value} when present and :not_found when missing. Empty values are therefore distinct from missing keys. Keys must be non-empty binaries no larger than LMDB's runtime maximum key size. Native read failures return {:error, reason}. The value is copied and no transaction or zero-copy view escapes the call.

@spec info(LeanLmdb.Environment.t() | LeanLmdb.Database.t()) ::
  map() | {:error, :invalid_environment}

Returns deterministic lifecycle information for an environment or database.

Environment maps contain :resource_id, canonical :path, :map_size, :max_dbs, :max_readers, and :read_only; database maps additionally contain :name. Invalid handles return {:error, :invalid_environment}.

@spec native_version() :: {String.t(), String.t()}

Returns the tuple {"lean_lmdb", version} without accessing LMDB or the filesystem.

@spec open(Path.t(), [open_option()]) ::
  {:ok, LeanLmdb.Environment.t()} | {:error, reason()}

Opens an LMDB environment, sharing native state for its canonical path.

The path is canonicalized after optional creation, so relative components and symlinks resolve to the same identity. Defaults are a 64 MiB map, 16 named databases, 126 readers, writable access, and create: true.

map_size must be between 1 MiB and 1 TiB and divisible by the operating system page size; max_dbs is limited to 1..1024 and max_readers to 1..4096. A read-only environment cannot be created. Repeats must use the same effective map size, limits, and read mode; create only controls path/open existence behavior.

Returns {:ok, environment} or {:error, reason}. Invalid paths/options, missing paths, incompatible repeated opens, resource-ID exhaustion, and native open failures are reported as stable reasons. The map never grows automatically. Only LMDB's default synchronized durability flags are used.

@spec open_database(LeanLmdb.Environment.t(), binary()) ::
  {:ok, LeanLmdb.Database.t()} | {:error, reason()}

Opens an existing named binary database.

Names follow the same UTF-8, length, and NUL restrictions as create_database/2. Returns {:ok, database}, {:error, :database_not_found}, or another documented lifecycle error.

@spec put(LeanLmdb.Database.t(), binary(), binary()) :: :ok | {:error, reason()}

Stores value under key, overwriting any prior value.

Keys and values are used as raw binaries; no serialization is performed. Returns :ok after commit or {:error, reason} without a partial commit.

@spec registry_info() :: %{
  live: non_neg_integer(),
  stale: non_neg_integer(),
  total: non_neg_integer()
}

Returns process-local registry counts and prunes stale weak entries.

This exposes counts only; it never reveals native pointers. It is intended for deterministic lifecycle diagnostics and tests. The returned map always has non-negative :live, :stale, and :total counts.

@spec scan(LeanLmdb.Database.t(), [scan_option()]) ::
  {:ok, [{binary(), binary()}], :done | binary()} | {:error, reason()}

Returns one bounded page of binary key/value pairs in ascending key order.

A scan is either a prefix scan (prefix: binary) or an explicit range scan. Range endpoints default to nil; the lower endpoint is inclusive and the upper endpoint exclusive by default. Prefix cannot be mixed with from, to, or the inclusivity options. Prefixes and endpoints are at most 511 bytes. limit defaults to 100 (maximum 10,000) and max_bytes defaults to 1 MiB (maximum 64 MiB), counting key plus value bytes.

The third result element is :done or an opaque continuation binary. Pass the continuation with the same database and bounds to resume exclusively after the last emitted key. Page limits may change while resuming. If the first eligible row exceeds max_bytes, the call returns {:error, :row_too_large} and no rows, making the output byte budget a hard bound. Invalid options/tokens and native read failures also return {:error, reason}. Pages do not share a snapshot and all row/token bytes are copied before the call returns.

@spec write_batch(LeanLmdb.Environment.t(), [batch_operation()]) ::
  :ok | {:error, reason()}

Applies an ordered list of puts and deletes atomically across named databases.

Every database must belong to exactly the supplied environment. The complete list is validated before one write transaction is opened, operations are applied in list order, and missing deletes are idempotent. Empty batches are valid no-ops. A batch is limited to 10,000 operations and 64 MiB of aggregate key and value bytes. Returns :ok only after commit; validation, mixed environments, read-only access, and LMDB failures return {:error, reason} with the transaction aborted.