# LiteStash (Elixir)

[![Hex.pm](https://img.shields.io/hexpm/v/litestash.svg)](https://hex.pm/packages/litestash)
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/litestash/)
[![License](https://img.shields.io/hexpm/l/litestash.svg)](https://github.com/nortosem/LiteStash)

**High-performance key-value store using SQLite static lock sharding.**

This is the native Elixir client for the **LiteStash** database ecosystem. It acts as a high-performance Host that drives the `litestash-engine` storage appliance via a strictly typed MessagePack protocol.

> **⚠️ Status: Pre-Alpha / Namespace Reservation**
> This package is currently being architected. The API below is provisional.

## Architecture

LiteStash uses **Application-Side Static Lock Sharding**.
1.  **The Client (Elixir)** determines the routing topology (hashing keys to specific shard files).
2.  **The Engine (Python/Native Binary)** manages the ACID persistence via SQLAlchemy/SQLite.
3.  **The Bridge** communicates via Standard I/O using binary MessagePack frames.

This architecture allows high-concurrency writes by distributing lock contention across multiple deterministic SQLite files.

## Installation

Add `litestash` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:litestash, "~> 0.1.0-alpha.1"}
  ]
end
```

### System Requirements

This library requires the **LiteStash Engine** to be present in your system path.

```bash
# Install the engine 
pip install litestash-engine
```

## Usage (Planned API)

```elixir
# Start the connection (spawns the engine sidecar)
{:ok, pid} = LiteStash.start_link(data_dir: "./data")

# Write a value (Primitive, Map, List, or Vector)
# Routing and sharding happen automatically based on the key hash.
:ok = LiteStash.set("user:1001", %{name: "Alice", score: 99})

# Read a value
{:ok, val} = LiteStash.get("user:1001")
# => %{"name" => "Alice", "score" => 99}

# Vector Storage (Stored as Arrays)
:ok = LiteStash.set("vec:1", [0.1, 0.5, 0.9])
```

## The Universal Data Contract

All data written by this client is byte-for-byte compatible with the Python and Rust implementations.

*   **Hashing:** BLAKE2b-512 (Canonical/Raw).
*   **Protocol:** MsgPack with 4-byte Big-Endian framing.
*   **Schema:** Universal 5-column SQLite layout.

## License

Apache 2.0