55349845d0
Break monolith source files into focused modules: - stemedb-core/types.rs → types/ directory (assertion, source, gold_standard, etc.) - stemedb-storage: audit_store, quota_store, trust_rank_store, vector_index, vote_store → module directories - stemedb-ingest/worker.rs → worker/ with separate test modules - stemedb-query: engine, materializer, query → module directories - stemedb-lens: epoch_aware, skeptic → module directories - stemedb-sim/lib.rs → agent, arenas/, helpers, runner, strategy, types - stemedb-api/tests: integration_tests → http_basic, http_validation, http_epoch, http_pipeline - stemedb-api/tests: e2e_flow_test → e2e_full_pipeline, e2e_lens_resolution - stemedb-query/tests: e2e_pipeline → e2e_pipeline + e2e_decay Also adds new features: gold standard verification, escalation handlers, admin endpoints, concept hierarchy spec, arena roadmap, and Go SDK. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
108 lines
6.0 KiB
Markdown
108 lines
6.0 KiB
Markdown
# Episteme (StemeDB)
|
|
|
|
A probabilistic knowledge graph database that stores Claims, not Facts. Append-only Merkle DAG with read-time resolution via Lenses.
|
|
|
|
**Core Concept:** "Git for Truth" - conflicting assertions coexist, resolved at query time through Consensus, Recency, Authority, or custom Lenses.
|
|
|
|
## Find Your Guide
|
|
|
|
| If you need to... | Read this |
|
|
|-------------------|-----------|
|
|
| **Get started fast** | [quickstart.md](./quickstart.md) |
|
|
| **Understand what Episteme is** | [what-is-episteme.md](./what-is-episteme.md) |
|
|
| **Understand the technical vision** | [vision.md](./vision.md) |
|
|
| **See use cases** | [use-cases/README.md](./use-cases/README.md) |
|
|
| **Understand architecture** | [architecture.md](./architecture.md) |
|
|
| **Learn data structures** | [docs/data-structures.md](./docs/data-structures.md) |
|
|
| **See the roadmap** | [roadmap.md](./roadmap.md) |
|
|
| **Build apps on Episteme** | [docs/app-concepts/index.md](./docs/app-concepts/index.md) |
|
|
| **Consumer Health vertical** | [docs/app-concepts/consumer-health.md](./docs/app-concepts/consumer-health.md) |
|
|
| **Use Go SDK** | [ai-lookup/services/sdk.md](ai-lookup/services/sdk.md) |
|
|
| **Write Rust code** | [.claude/guides/backend/rust-guidelines.md](.claude/guides/backend/rust-guidelines.md) |
|
|
| **Set up local dev** | [.claude/guides/local/setup.md](.claude/guides/local/setup.md) |
|
|
| **Run tests** | [.claude/guides/local/testing.md](.claude/guides/local/testing.md) |
|
|
| **Understand quality checks** | [.claude/guides/local/quality-checks.md](.claude/guides/local/quality-checks.md) |
|
|
| **Learn about simulation** | [ai-lookup/features/simulation.md](ai-lookup/features/simulation.md) |
|
|
| **Advance the simulator** | [arena-roadmap.md](./arena-roadmap.md) |
|
|
| **Work on storage/DAG** | Load skill: `stemedb-core` |
|
|
| **Implement a Lens** | Load skill: `stemedb-lens` |
|
|
| **Plan a milestone** | `/plan-milestone` command |
|
|
| **Analyze use case gaps** | `/analyze-gaps` command |
|
|
| **Add an API endpoint** | [.claude/guides/backend/api-endpoints.md](.claude/guides/backend/api-endpoints.md) |
|
|
| **Integrate with AI tools** | [.claude/guides/integrations/ai-coding-assistant-integration.md](.claude/guides/integrations/ai-coding-assistant-integration.md) |
|
|
| **ADK-Go + Episteme** | [.claude/guides/integrations/adk-go-episteme.md](.claude/guides/integrations/adk-go-episteme.md) |
|
|
| **Distributed architecture** | [docs/research/distributed-write-path.md](docs/research/distributed-write-path.md) |
|
|
|
|
## Critical Rules
|
|
|
|
- **Append-Only:** NEVER mutate existing Assertions. Create new ones.
|
|
- **Content-Addressed:** Assertion ID = BLAKE3 hash of content.
|
|
- **No Unwrap:** NEVER use `unwrap()` or `expect()` in production code. CI enforces via `clippy::unwrap_used` and `clippy::expect_used` at deny level.
|
|
- **Defensive Writes:** All writes go through WAL with fsync.
|
|
- **Zero-Copy:** Use `rkyv` for serialization. ALWAYS use `stemedb_core::serde::{serialize, deserialize}` — NEVER use raw `AllocSerializer` in production code.
|
|
- **Instrument Critical Paths:** Use `#[instrument]` on public methods in WAL, storage, ingestion, and lens code. Include meaningful fields (key_len, payload_len, offset, candidates_count, lens).
|
|
- **Structured Logging:** Use `tracing` (info!, warn!, error!) instead of `println!`/`eprintln!`. Clippy enforces via `print_stdout`/`print_stderr` at warn level. CLI binaries (e.g., `stemedb-sim`) may use `#![allow()]` for user-facing output.
|
|
- **Document Changes:** Update `ai-lookup/` when adding new types/concepts. Keep skills in sync with code.
|
|
- **No Git Operations:** NEVER use git stash, git branch, git checkout, or any git operations unless the user explicitly tells you to.
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Build
|
|
cargo build --workspace
|
|
|
|
# Test
|
|
cargo test --workspace
|
|
|
|
# Lint (must pass before commit)
|
|
cargo clippy --workspace -- -D warnings
|
|
cargo fmt --check
|
|
```
|
|
|
|
## Specialized Agents
|
|
|
|
| Domain | Agent | When to use |
|
|
|--------|-------|-------------|
|
|
| **Product Vision** | `episteme-product-visionary` | Use cases, "why not Postgres?", product-market fit |
|
|
| General Rust | `primary-developer` | Feature implementation, refactoring |
|
|
| Code Quality | `rust-quality-engineer` | Reviews, test coverage, clippy |
|
|
| Storage | `storage-engine-architect` | WAL, LSM, crash recovery |
|
|
| Graph Engine | `rust-graph-engine-architect` | Lock-free structures, cache optimization |
|
|
| Defensive | `defensive-systems-architect` | Rate limiting, circuit breakers, hostile input |
|
|
| Distributed | `distributed-systems-engineer` | CRDT replication, Raft coordination, Merkle sync, clustering |
|
|
| Lenses | `stemedb-lens-architect` | Query resolution, ranking algorithms |
|
|
| Planning | `stemedb-planner` | Milestone planning, roadmap |
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
Write Path (Spine): Read Path (Cortex):
|
|
[Agent] -> [Ingestion] [Agent] <- [Lens Engine]
|
|
| |
|
|
v |
|
|
[WAL/Fsync] [Index Lookup]
|
|
| |
|
|
v |
|
|
[KV Store] <--------------------+
|
|
```
|
|
|
|
## Crates
|
|
|
|
| Crate | Purpose | Status |
|
|
|-------|---------|--------|
|
|
| `stemedb-core` | Assertion, LifecycleStage, MaterializedView, types | ✅ Implemented |
|
|
| `stemedb-wal` | Write-ahead log with crash recovery | ✅ Implemented |
|
|
| `stemedb-storage` | KVStore, VoteStore, IndexStore, TrustRankStore | ✅ Implemented |
|
|
| `stemedb-ingest` | Ingestion pipeline with signature verification | ✅ Implemented |
|
|
| `stemedb-query` | Query engine, Materializer for O(1) MV: reads | ✅ Implemented |
|
|
| `stemedb-lens` | Lenses (Recency, Consensus, Authority, Vote/Trust-aware) | ✅ Implemented |
|
|
| `stemedb-api` | HTTP API with axum + utoipa OpenAPI docs | ✅ Implemented |
|
|
| `stemedb-sim` | Simulation for testing the pipeline | ✅ Implemented |
|
|
|
|
## SDKs
|
|
|
|
| SDK | Purpose | Status |
|
|
|-----|---------|--------|
|
|
| `sdk/go/steme` | Go HTTP client with Ed25519 signing and fluent builders | ✅ Implemented |
|
|
| `sdk/go/adk` | ADK-Go tools and callbacks for AI agents | ✅ Implemented |
|