aarondb

# AaronDB

[![Hex](https://img.shields.io/hexpm/v/aarondb.svg)](https://hex.pm/packages/aarondb)

AaronDB is a local, embedded Datalog database for the BEAM. Its documented Stable labels are narrow local contracts backed by committed tests, bounded failure behavior where relevant, reproducible harnesses, and CI; see the [evidence index](docs/evidence.md).

> "Simplicity is not about making things easy. It is about untangling complexity." — Rich Hickey

> **Current release line:** v4.1.0 defines evidence-backed **local** Stable contracts for vector/HNSW, BM25, graph analytics, and federation. See [Feature Maturity](docs/feature_maturity.md) and [ADR 0002](docs/adr/0002-embedded-local-mcp-boundary.md).

AaronDB is a BEAM-native temporal Datalog engine written in Gleam. Its strongest shape is a fact-oriented database core built around a transactor actor, immutable-style state transitions, in-memory indexes, and a custom query engine.

This repository also contains local search, graph analytics, federation, cognitive, sharding, and MCP extensions. Their supported contracts are deliberately narrow; read `docs/feature_maturity.md` and `docs/project_boundaries.md` before adopting non-core features.

## Core Model

1. Facts, not objects: data is represented as datoms.
2. Actor-owned writes: a transactor process serializes state transitions.
3. Query over values: reads execute against database state snapshots.
4. Storage is pluggable: the engine is decoupled from persistence adapters.

## What Is Solid Today

- In-memory transactional core
- Datom model with transaction and valid-time fields
- Query DSL and interpreted query execution
- Pull, history, diff, and speculative state evaluation
- Constraints for uniqueness, cardinality, predicates, and composites
- Local Stable retrieval/analytics contracts with committed regression and benchmark evidence

## Maturity Snapshot

| Area | Status | Notes |
| --- | --- | --- |
| Core DB API (`aarondb`) | Stable | Primary strength of the repository |
| Query DSL and pull APIs | Stable | Backed by passing tests |
| Vector / HNSW | Stable (local approximate) | Deterministic evidence and exact-oracle comparison; no universal SLA |
| BM25 | Stable (local primitive) | Immutable, sequential, caller-owned Analyzer v1 index |
| Graph analytics | Stable (local bounded API) | Directed graph model; bounded APIs are the supported path for arbitrary data |
| Local federation | Stable (local fail-fast reads) | Named in-runtime sources, provenance, typed failure; no partial results |
| Temporal querying and diff | Stable (local bounded API) | Transaction-time, valid-time, and bitemporal snapshots plus deterministic bounded diffs; legacy unbounded APIs are compatibility-only |
| Reactive subscriptions | Stable (local mailbox delivery) | Serialized initial/delta/unsubscribe ordering; consumers own mailbox draining |
| Cognitive memory | Stable (local explicit-fact solver) | Explicit relevance facts with deterministic lifecycle semantics; no learned ranking or external retrieval |
| Virtual predicates | Stable (bounded local adapters) | Typed local adapter results and row bounds; no remote transport or forced interruption |
| Sharding and distributed queries | Local Beta | One-runtime scatter/gather only: no remote membership, failover, transactional migration, or exact global Avg/Median |
| Raft and HA claims | Inactive stub | Pure leader-election state machine exists but is **not wired into the engine** (election-only; no log replication) |
| Mnesia persistence | Recovery-oriented | Initialization preserves incompatible schemas and returns an error; explicit backup/migration/reset is required |
| MCP server and agent tooling | Local Beta | Local stdio JSON-RPC adapter exposes three implemented tools; no network listener or remote authentication |

## Explicitly local means exactly that

The Stable labels above are contracts for one BEAM runtime and stated, reproducible local evidence. They do **not** claim remote federation, replication, high availability, failover, migration, quorum, coordinated writes, global snapshots, distributed graph processing, or universal latency/memory/recall guarantees.

- **Vector:** [cosine HNSW contract](docs/manual/vector_search.md) plus exact oracle, recall/churn regression, and benchmark harness.
- **BM25:** [Analyzer v1 and lifecycle contract](docs/manual/bm25_search.md); no transaction integration, persistence, or concurrent mutation safety.
- **Graph:** [directed bounded analytics contract](docs/manual/graph_queries.md); legacy APIs remain unbounded compatibility paths.
- **Temporal/Diff:** [bounded local snapshot and diff contract](docs/manual/temporal_diff.md), with lifecycle/invariant tests and a reproducible [CI evidence harness](docs/benchmarks/temporal_diff.md); no remote/global snapshots or universal performance claims.
- **Federation:** [local fail-fast read contract](docs/manual/local_federation.md); no cross-source transaction/snapshot, retries, or partial result mode.

## Installation

Add the current release to your `gleam.toml`:

```toml
[dependencies]
aarondb = "4.1.0"
```

## What 4.1.0 Changes

AaronDB 4.1.0 promotes four capabilities only within evidence-backed local boundaries:

- **Vector/HNSW** — deterministic test configuration, exact cosine oracle, recall corpus, lifecycle churn regression, and reproducible local benchmark.
- **BM25** — Analyzer v1, deterministic golden ranking/lifecycle tests, incremental-vs-rebuild evidence, and reproducible local benchmark.
- **Graph** — directed semantics, canonical/budget regression coverage, bounded traversal/global APIs, and representative local fixture benchmarks.
- **Federation** — per-source execution, deterministic provenance/order, typed fail-fast unavailable/timeout errors, no partial result leakage, and a local soak harness.

The release does not turn AaronDB into a distributed system. See [CHANGELOG.md](CHANGELOG.md) for the full release notes.

## Basic Usage

Create an in-memory database:

```gleam
import aarondb

let db = aarondb.new()
```

Transact facts:

```gleam
import aarondb
import aarondb/fact.{EntityId, Str, Uid}

let assert Ok(_state) = aarondb.transact(db, [
  #(Uid(EntityId(101)), "user/name", Str("Alice")),
  #(Uid(EntityId(101)), "user/role", Str("Admin")),
])
```

Query with the DSL:

```gleam
import aarondb
import aarondb/q

let query =
  q.select(["name"])
  |> q.where(q.v("e"), "user/role", q.s("Admin"))
  |> q.where(q.v("e"), "user/name", q.v("name"))
  |> q.to_clauses()

let results = aarondb.query(db, query)
```

Use temporal and pull APIs:

```gleam
import aarondb
import aarondb/fact

let history = aarondb.history(db, fact.Uid(fact.EntityId(101)))
let entity = aarondb.pull(db, fact.Uid(fact.EntityId(101)), aarondb.pull_all())
```

## Documentation

- [Architecture](docs/architecture.md)
- [Feature Maturity](docs/feature_maturity.md)
- [Project Boundaries](docs/project_boundaries.md)
- [Query DSL](docs/manual/query_dsl.md)
- [Local MCP stdio adapter](docs/manual/mcp_stdio.md)
- [Supervision](docs/manual/supervision.md)
- [Vector search contract](docs/manual/vector_search.md)
- [BM25 search contract](docs/manual/bm25_search.md)
- [Graph query contract](docs/manual/graph_queries.md)
- [Local federation contract](docs/manual/local_federation.md)
- [Distributed Guide](docs/distributed_guide.md)

## Current Recommendation

Treat AaronDB first as a temporal Datalog engine with a strong in-memory core. The v4.1 local contracts are ready for their stated use, but distributed features remain deliberately separate work—not marketing adjectives.